dongsheng@627: #: ../en/00book.xml:41 dongsheng@627: msgid "Mercurial: The Definitive Guide" dongsheng@627: msgstr "Mercurial 权威指南" dongsheng@627: dongsheng@627: #. type: Content of: <book><subtitle> dongsheng@627: #: ../en/00book.xml:46 dongsheng@627: msgid "Compiled from $rev_id$" dongsheng@627: msgstr "编译自 $rev_id$" dongsheng@627: dongsheng@627: #. type: Content of: <book><bookinfo><authorgroup><author><firstname> dongsheng@627: #: ../en/00book.xml:50 dongsheng@627: msgid "Bryan" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><bookinfo><authorgroup><author><surname> dongsheng@627: #: ../en/00book.xml:51 dongsheng@627: msgid "O'Sullivan" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><bookinfo> dongsheng@627: #: ../en/00book.xml:55 dongsheng@627: msgid "" dongsheng@627: "<editor> <firstname>Mike</firstname> <surname>Loukides</surname> </editor> " dongsheng@627: "<copyright> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</" dongsheng@627: "year> <holder>Bryan O'Sullivan</holder> </copyright>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><title> dongsheng@627: #: ../en/appA-cmdref.xml:4 dongsheng@627: msgid "Command reference" dongsheng@627: msgstr "命令参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appA-cmdref.xml:6 dongsheng@627: msgid "" dongsheng@627: "\\cmdref{add}{add files at the next commit} \\optref{add}{I}{include} \\optref" dongsheng@627: "{add}{X}{exclude} \\optref{add}{n}{dry-run}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appA-cmdref.xml:11 dongsheng@627: msgid "\\cmdref{diff}{print changes in history or working directory}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appA-cmdref.xml:13 dongsheng@627: msgid "" dongsheng@627: "Show differences between revisions for the specified files or directories, " dongsheng@627: "using the unified diff format. For a description of the unified diff format, " dongsheng@627: "see section <xref linkend=\"sec.mq.patch\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appA-cmdref.xml:17 dongsheng@627: msgid "" dongsheng@627: "By default, this command does not print diffs for files that Mercurial " dongsheng@627: "considers to contain binary data. To control this behaviour, see the <option " dongsheng@627: "role=\"hg-opt-diff\">-a</option> and <option role=\"hg-opt-diff\">--git</" dongsheng@627: "option> options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><title> dongsheng@627: #: ../en/appA-cmdref.xml:22 dongsheng@627: msgid "Options" dongsheng@627: msgstr "选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:24 dongsheng@627: msgid "\\loptref{diff}{nodates}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:26 dongsheng@627: msgid "Omit date and time information when printing diff headers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:28 dongsheng@627: msgid "\\optref{diff}{B}{ignore-blank-lines}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:30 dongsheng@627: msgid "" dongsheng@627: "Do not print changes that only insert or delete blank lines. A line that " dongsheng@627: "contains only whitespace is not considered blank." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:34 dongsheng@627: msgid "\\optref{diff}{I}{include}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:37 dongsheng@627: msgid "Include files and directories whose names match the given patterns." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:40 dongsheng@627: msgid "\\optref{diff}{X}{exclude}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:43 dongsheng@627: msgid "Exclude files and directories whose names match the given patterns." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:46 dongsheng@627: msgid "\\optref{diff}{a}{text}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:49 dongsheng@627: msgid "" dongsheng@627: "If this option is not specified, <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "will refuse to print diffs for files that it detects as binary. Specifying " dongsheng@627: "<option role=\"hg-opt-diff\">-a</option> forces <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command> to treat all files as text, and generate diffs for all of them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:55 dongsheng@627: msgid "" dongsheng@627: "This option is useful for files that are <quote>mostly text</quote> but have " dongsheng@627: "a few embedded NUL characters. If you use it on files that contain a lot of " dongsheng@627: "binary data, its output will be incomprehensible." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:60 dongsheng@627: msgid "\\optref{diff}{b}{ignore-space-change}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:63 dongsheng@627: msgid "" dongsheng@627: "Do not print a line if the only change to that line is in the amount of white " dongsheng@627: "space it contains." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:67 dongsheng@627: msgid "\\optref{diff}{g}{git}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:70 dongsheng@627: msgid "" dongsheng@627: "Print <command>git</command>-compatible diffs. XXX reference a format " dongsheng@627: "description." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:74 dongsheng@627: msgid "\\optref{diff}{p}{show-function}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:77 dongsheng@627: msgid "" dongsheng@627: "Display the name of the enclosing function in a hunk header, using a simple " dongsheng@627: "heuristic. This functionality is enabled by default, so the <option role=" dongsheng@627: "\"hg-opt-diff\">-p</option> option has no effect unless you change the value " dongsheng@627: "of the <envar role=\"rc-item-diff\">showfunc</envar> config item, as in the " dongsheng@627: "following example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:84 dongsheng@627: msgid "\\optref{diff}{r}{rev}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:87 dongsheng@627: msgid "" dongsheng@627: "Specify one or more revisions to compare. The <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command> command accepts up to two <option role=\"hg-opt-diff\">-r</" dongsheng@627: "option> options to specify the revisions to compare." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:93 dongsheng@627: msgid "" dongsheng@627: "Display the differences between the parent revision of the working directory " dongsheng@627: "and the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:97 dongsheng@627: msgid "" dongsheng@627: "Display the differences between the specified changeset and the working " dongsheng@627: "directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:101 dongsheng@627: msgid "Display the differences between the two specified changesets." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:105 dongsheng@627: msgid "" dongsheng@627: "You can specify two revisions using either two <option role=\"hg-opt-diff\">-" dongsheng@627: "r</option> options or revision range notation. For example, the two revision " dongsheng@627: "specifications below are equivalent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:112 dongsheng@627: msgid "" dongsheng@627: "When you provide two revisions, Mercurial treats the order of those revisions " dongsheng@627: "as significant. Thus, <command role=\"hg-cmd\">hg diff -r10:20</command> " dongsheng@627: "will produce a diff that will transform files from their contents as of " dongsheng@627: "revision 10 to their contents as of revision 20, while <command role=\"hg-cmd" dongsheng@627: "\">hg diff -r20:10</command> means the opposite: the diff that will transform " dongsheng@627: "files from their revision 20 contents to their revision 10 contents. You " dongsheng@627: "cannot reverse the ordering in this way if you are diffing against the " dongsheng@627: "working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:122 dongsheng@627: msgid "\\optref{diff}{w}{ignore-all-space}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:125 dongsheng@627: msgid "\\cmdref{version}{print version and copyright information}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:128 dongsheng@627: msgid "" dongsheng@627: "This command displays the version of Mercurial you are running, and its " dongsheng@627: "copyright license. There are four kinds of version string that you may see." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:133 dongsheng@627: msgid "" dongsheng@627: "The string <quote><literal>unknown</literal></quote>. This version of " dongsheng@627: "Mercurial was not built in a Mercurial repository, and cannot determine its " dongsheng@627: "own version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:138 dongsheng@627: msgid "" dongsheng@627: "A short numeric string, such as <quote><literal>1.1</literal></quote>. This " dongsheng@627: "is a build of a revision of Mercurial that was identified by a specific tag " dongsheng@627: "in the repository where it was built. (This doesn't necessarily mean that " dongsheng@627: "you're running an official release; someone else could have added that tag to " dongsheng@627: "any revision in the repository where they built Mercurial.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:146 dongsheng@627: msgid "" dongsheng@627: "A hexadecimal string, such as <quote><literal>875489e31abe</literal></" dongsheng@627: "quote>. This is a build of the given revision of Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:150 dongsheng@627: msgid "" dongsheng@627: "A hexadecimal string followed by a date, such as <quote><literal>875489e31abe" dongsheng@627: "+20070205</literal></quote>. This is a build of the given revision of " dongsheng@627: "Mercurial, where the build repository contained some local changes that had " dongsheng@627: "not been committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><title> dongsheng@627: #: ../en/appA-cmdref.xml:159 dongsheng@627: msgid "Tips and tricks" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><title> dongsheng@627: #: ../en/appA-cmdref.xml:162 dongsheng@627: msgid "" dongsheng@627: "Why do the results of <command role=\"hg-cmd\">hg diff</command> and <command " dongsheng@627: "role=\"hg-cmd\">hg status</command> differ?" dongsheng@627: msgstr "" dongsheng@627: "为什么 <command role=\"hg-cmd\">hg diff</command> 与 <command role=\"hg-cmd" dongsheng@627: "\">hg status</command> 的结果不同 ?" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:164 dongsheng@627: msgid "" dongsheng@627: "When you run the <command role=\"hg-cmd\">hg status</command> command, you'll " dongsheng@627: "see a list of files that Mercurial will record changes for the next time you " dongsheng@627: "perform a commit. If you run the <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "command, you may notice that it prints diffs for only a <emphasis>subset</" dongsheng@627: "emphasis> of the files that <command role=\"hg-cmd\">hg status</command> " dongsheng@627: "listed. There are two possible reasons for this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:171 dongsheng@627: msgid "" dongsheng@627: "The first is that <command role=\"hg-cmd\">hg status</command> prints some " dongsheng@627: "kinds of modifications that <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "doesn't normally display. The <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "command normally outputs unified diffs, which don't have the ability to " dongsheng@627: "represent some changes that Mercurial can track. Most notably, traditional " dongsheng@627: "diffs can't represent a change in whether or not a file is executable, but " dongsheng@627: "Mercurial records this information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:179 dongsheng@627: msgid "" dongsheng@627: "If you use the <option role=\"hg-opt-diff\">--git</option> option to <command " dongsheng@627: "role=\"hg-cmd\">hg diff</command>, it will display <command>git</command>-" dongsheng@627: "compatible diffs that <emphasis>can</emphasis> display this extra information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:184 dongsheng@627: msgid "" dongsheng@627: "The second possible reason that <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "might be printing diffs for a subset of the files displayed by <command role=" dongsheng@627: "\"hg-cmd\">hg status</command> is that if you invoke it without any " dongsheng@627: "arguments, <command role=\"hg-cmd\">hg diff</command> prints diffs against " dongsheng@627: "the first parent of the working directory. If you have run <command role=" dongsheng@627: "\"hg-cmd\">hg merge</command> to merge two changesets, but you haven't yet " dongsheng@627: "committed the results of the merge, your working directory has two parents " dongsheng@627: "(use <command role=\"hg-cmd\">hg parents</command> to see them). While " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> prints modifications relative to " dongsheng@627: "<emphasis>both</emphasis> parents after an uncommitted merge, <command role=" dongsheng@627: "\"hg-cmd\">hg diff</command> still operates relative only to the first " dongsheng@627: "parent. You can get it to print diffs relative to the second parent by " dongsheng@627: "specifying that parent with the <option role=\"hg-opt-diff\">-r</option> " dongsheng@627: "option. There is no way to print diffs relative to both parents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><title> dongsheng@627: #: ../en/appA-cmdref.xml:200 dongsheng@627: msgid "Generating safe binary diffs" dongsheng@627: msgstr "生成安全的二进制差异" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:202 dongsheng@627: msgid "" dongsheng@627: "If you use the <option role=\"hg-opt-diff\">-a</option> option to force " dongsheng@627: "Mercurial to print diffs of files that are either <quote>mostly text</quote> " dongsheng@627: "or contain lots of binary data, those diffs cannot subsequently be applied by " dongsheng@627: "either Mercurial's <command role=\"hg-cmd\">hg import</command> command or " dongsheng@627: "the system's <command>patch</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:209 dongsheng@627: msgid "" dongsheng@627: "If you want to generate a diff of a binary file that is safe to use as input " dongsheng@627: "for <command role=\"hg-cmd\">hg import</command>, use the <command role=\"hg-" dongsheng@627: "cmd\">hg diff</command>{--git} option when you generate the patch. The " dongsheng@627: "system <command>patch</command> command cannot handle binary patches at all." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><title> dongsheng@627: #: ../en/appB-mq-ref.xml:5 dongsheng@627: msgid "Mercurial Queues reference" dongsheng@627: msgstr "Mercurial 队列参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appB-mq-ref.xml:8 dongsheng@627: msgid "MQ command reference" dongsheng@627: msgstr "MQ 命令参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appB-mq-ref.xml:10 dongsheng@627: msgid "" dongsheng@627: "For an overview of the commands provided by MQ, use the command <command role=" dongsheng@627: "\"hg-cmd\">hg help mq</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:14 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qapplied</command>&emdash;print applied patches" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qapplied</command>&emdash;显示已应用的补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:17 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qapplied</command> command prints the current " dongsheng@627: "stack of applied patches. Patches are printed in oldest-to-newest order, so " dongsheng@627: "the last patch in the list is the <quote>top</quote> patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:24 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qcommit</command>&emdash;commit changes in the " dongsheng@627: "queue repository" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qcommit</command>&emdash;提交队列中的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:27 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qcommit</command> command commits any " dongsheng@627: "outstanding changes in the <filename role=\"special\" class=\"directory\">.hg/" dongsheng@627: "patches</filename> repository. This command only works if the <filename role=" dongsheng@627: "\"special\" class=\"directory\">.hg/patches</filename> directory is a " dongsheng@627: "repository, i.e. you created the directory using <command role=\"hg-cmd\">hg " dongsheng@627: "qinit <option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option></command> or ran " dongsheng@627: "<command role=\"hg-cmd\">hg init</command> in the directory after running " dongsheng@627: "<command role=\"hg-ext-mq\">qinit</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:39 dongsheng@627: msgid "" dongsheng@627: "This command is shorthand for <command role=\"hg-cmd\">hg commit --cwd .hg/" dongsheng@627: "patches</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:42 dongsheng@627: msgid "" dongsheng@627: "\\subsection{<command role=\"hg-ext-mq\">qdelete</command>&emdash;delete a " dongsheng@627: "patch from the <filename role=\"special\">series</filename> file}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:47 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qdelete</command> command removes the entry " dongsheng@627: "for a patch from the <filename role=\"special\">series</filename> file in the " dongsheng@627: "<filename role=\"special\" class=\"directory\">.hg/patches</filename> " dongsheng@627: "directory. It does not pop the patch if the patch is already applied. By " dongsheng@627: "default, it does not delete the patch file; use the <option role=\"hg-ext-mq-" dongsheng@627: "cmd-qdel-opt\">-f</option> option to do that." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:56 ../en/appB-mq-ref.xml:98 ../en/appB-mq-ref.xml:156 dongsheng@627: #: ../en/appB-mq-ref.xml:196 ../en/appB-mq-ref.xml:263 dongsheng@627: #: ../en/appB-mq-ref.xml:334 ../en/appB-mq-ref.xml:403 dongsheng@627: #: ../en/appB-mq-ref.xml:496 dongsheng@627: msgid "Options:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:58 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qdel-opt\">-f</option>: Delete the patch file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:65 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qdiff</command>&emdash;print a diff of the " dongsheng@627: "topmost applied patch" dongsheng@627: msgstr "" dongsheng@627: "<command role=\"hg-ext-mq\">qdiff</command>&emdash;显示最新应用补丁的差异" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:68 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qdiff</command> command prints a diff of the " dongsheng@627: "topmost applied patch. It is equivalent to <command role=\"hg-cmd\">hg diff -" dongsheng@627: "r-2:-1</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:74 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qfold</command>&emdash;merge (<quote>fold</" dongsheng@627: "quote>) several patches into one" dongsheng@627: msgstr "" dongsheng@627: "<command role=\"hg-ext-mq\">qfold</command>&emdash;将多个补丁合并(<quote>折叠" dongsheng@627: "</quote>)成一个" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:77 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qfold</command> command merges multiple " dongsheng@627: "patches into the topmost applied patch, so that the topmost applied patch " dongsheng@627: "makes the union of all of the changes in the patches in question." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:82 dongsheng@627: msgid "" dongsheng@627: "The patches to fold must not be applied; <command role=\"hg-ext-mq\">qfold</" dongsheng@627: "command> will exit with an error if any is. The order in which patches are " dongsheng@627: "folded is significant; <command role=\"hg-cmd\">hg qfold a b</command> means " dongsheng@627: "<quote>apply the current topmost patch, followed by <literal>a</literal>, " dongsheng@627: "followed by <literal>b</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:90 dongsheng@627: msgid "" dongsheng@627: "The comments from the folded patches are appended to the comments of the " dongsheng@627: "destination patch, with each block of comments separated by three asterisk " dongsheng@627: "(<quote><literal>*</literal></quote>) characters. Use the <option role=\"hg-" dongsheng@627: "ext-mq-cmd-qfold-opt\">-e</option> option to edit the commit message for the " dongsheng@627: "combined patch/changeset after the folding has completed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:100 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qfold-opt\">-e</option>: Edit the commit message " dongsheng@627: "and patch description for the newly folded patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:105 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qfold-opt\">-l</option>: Use the contents of the " dongsheng@627: "given file as the new commit message and patch description for the folded " dongsheng@627: "patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:110 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qfold-opt\">-m</option>: Use the given text as " dongsheng@627: "the new commit message and patch description for the folded patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:118 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qheader</command>&emdash;display the header/" dongsheng@627: "description of a patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qheader</command>&emdash;显示补丁头部描述" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:122 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qheader</command> command prints the header, " dongsheng@627: "or description, of a patch. By default, it prints the header of the topmost " dongsheng@627: "applied patch. Given an argument, it prints the header of the named patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:129 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qimport</command>&emdash;import a third-party " dongsheng@627: "patch into the queue" dongsheng@627: msgstr "" dongsheng@627: "<command role=\"hg-ext-mq\">qimport</command>&emdash;将第三方补丁导入队列" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:132 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qimport</command> command adds an entry for " dongsheng@627: "an external patch to the <filename role=\"special\">series</filename> file, " dongsheng@627: "and copies the patch into the <filename role=\"special\" class=\"directory\">." dongsheng@627: "hg/patches</filename> directory. It adds the entry immediately after the " dongsheng@627: "topmost applied patch, but does not push the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:140 dongsheng@627: msgid "" dongsheng@627: "If the <filename role=\"special\" class=\"directory\">.hg/patches</filename> " dongsheng@627: "directory is a repository, <command role=\"hg-ext-mq\">qimport</command> " dongsheng@627: "automatically does an <command role=\"hg-cmd\">hg add</command> of the " dongsheng@627: "imported patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:148 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qinit</command>&emdash;prepare a repository to " dongsheng@627: "work with MQ" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qinit</command>&emdash;为使用 MQ 配置版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:151 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qinit</command> command prepares a repository " dongsheng@627: "to work with MQ. It creates a directory called <filename role=\"special\" " dongsheng@627: "class=\"directory\">.hg/patches</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:158 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option>: Create <filename role=" dongsheng@627: "\"special\" class=\"directory\">.hg/patches</filename> as a repository in its " dongsheng@627: "own right. Also creates a <filename role=\"special\">.hgignore</filename> " dongsheng@627: "file that will ignore the <filename role=\"special\">status</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:168 dongsheng@627: msgid "" dongsheng@627: "When the <filename role=\"special\" class=\"directory\">.hg/patches</" dongsheng@627: "filename> directory is a repository, the <command role=\"hg-ext-mq\">qimport</" dongsheng@627: "command> and <command role=\"hg-ext-mq\">qnew</command> commands " dongsheng@627: "automatically <command role=\"hg-cmd\">hg add</command> new patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:177 dongsheng@627: msgid "<command role=\"hg-ext-mq\">qnew</command>&emdash;create a new patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qnew</command>&emdash;创建新补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:180 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qnew</command> command creates a new patch. " dongsheng@627: "It takes one mandatory argument, the name to use for the patch file. The " dongsheng@627: "newly created patch is created empty by default. It is added to the " dongsheng@627: "<filename role=\"special\">series</filename> file after the current topmost " dongsheng@627: "applied patch, and is immediately pushed on top of that patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:188 dongsheng@627: msgid "" dongsheng@627: "If <command role=\"hg-ext-mq\">qnew</command> finds modified files in the " dongsheng@627: "working directory, it will refuse to create a new patch unless the <option " dongsheng@627: "role=\"hg-ext-mq-cmd-qnew-opt\">-f</option> option is used (see below). This " dongsheng@627: "behaviour allows you to <command role=\"hg-ext-mq\">qrefresh</command> your " dongsheng@627: "topmost applied patch before you apply a new patch on top of it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:198 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qnew-opt\">-f</option>: Create a new patch if " dongsheng@627: "the contents of the working directory are modified. Any outstanding " dongsheng@627: "modifications are added to the newly created patch, so after this command " dongsheng@627: "completes, the working directory will no longer be modified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:205 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qnew-opt\">-m</option>: Use the given text as " dongsheng@627: "the commit message. This text will be stored at the beginning of the patch " dongsheng@627: "file, before the patch data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:214 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qnext</command>&emdash;print the name of the next " dongsheng@627: "patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qnext</command>&emdash;显示下个补丁的名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:217 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qnext</command> command prints the name name " dongsheng@627: "of the next patch in the <filename role=\"special\">series</filename> file " dongsheng@627: "after the topmost applied patch. This patch will become the topmost applied " dongsheng@627: "patch if you run <command role=\"hg-ext-mq\">qpush</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:226 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qpop</command>&emdash;pop patches off the stack" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qpop</command>&emdash;删除堆栈顶部的补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:229 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpop</command> command removes applied " dongsheng@627: "patches from the top of the stack of applied patches. By default, it removes " dongsheng@627: "only one patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:233 dongsheng@627: msgid "" dongsheng@627: "This command removes the changesets that represent the popped patches from " dongsheng@627: "the repository, and updates the working directory to undo the effects of the " dongsheng@627: "patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:237 dongsheng@627: msgid "" dongsheng@627: "This command takes an optional argument, which it uses as the name or index " dongsheng@627: "of the patch to pop to. If given a name, it will pop patches until the named " dongsheng@627: "patch is the topmost applied patch. If given a number, <command role=\"hg-" dongsheng@627: "ext-mq\">qpop</command> treats the number as an index into the entries in the " dongsheng@627: "series file, counting from zero (empty lines and lines containing only " dongsheng@627: "comments do not count). It pops patches until the patch identified by the " dongsheng@627: "given index is the topmost applied patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:247 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpop</command> command does not read or write " dongsheng@627: "patches or the <filename role=\"special\">series</filename> file. It is thus " dongsheng@627: "safe to <command role=\"hg-ext-mq\">qpop</command> a patch that you have " dongsheng@627: "removed from the <filename role=\"special\">series</filename> file, or a " dongsheng@627: "patch that you have renamed or deleted entirely. In the latter two cases, " dongsheng@627: "use the name of the patch as it was when you applied it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:256 dongsheng@627: msgid "" dongsheng@627: "By default, the <command role=\"hg-ext-mq\">qpop</command> command will not " dongsheng@627: "pop any patches if the working directory has been modified. You can override " dongsheng@627: "this behaviour using the <option role=\"hg-ext-mq-cmd-qpop-opt\">-f</option> " dongsheng@627: "option, which reverts all modifications in the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:265 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpop-opt\">-a</option>: Pop all applied " dongsheng@627: "patches. This returns the repository to its state before you applied any " dongsheng@627: "patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:270 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpop-opt\">-f</option>: Forcibly revert any " dongsheng@627: "modifications to the working directory when popping." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:275 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpop-opt\">-n</option>: Pop a patch from the " dongsheng@627: "named queue." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:280 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpop</command> command removes one line from " dongsheng@627: "the end of the <filename role=\"special\">status</filename> file for each " dongsheng@627: "patch that it pops." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:287 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qprev</command>&emdash;print the name of the " dongsheng@627: "previous patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qprev</command>&emdash;显示上个补丁的名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:290 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qprev</command> command prints the name of " dongsheng@627: "the patch in the <filename role=\"special\">series</filename> file that comes " dongsheng@627: "before the topmost applied patch. This will become the topmost applied patch " dongsheng@627: "if you run <command role=\"hg-ext-mq\">qpop</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:299 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qpush</command>&emdash;push patches onto the stack" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qpush</command>&emdash;增加补丁到堆栈" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:302 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpush</command> command adds patches onto the " dongsheng@627: "applied stack. By default, it adds only one patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:306 dongsheng@627: msgid "" dongsheng@627: "This command creates a new changeset to represent each applied patch, and " dongsheng@627: "updates the working directory to apply the effects of the patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:310 dongsheng@627: msgid "The default data used when creating a changeset are as follows:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:313 dongsheng@627: msgid "" dongsheng@627: "The commit date and time zone are the current date and time zone. Because " dongsheng@627: "these data are used to compute the identity of a changeset, this means that " dongsheng@627: "if you <command role=\"hg-ext-mq\">qpop</command> a patch and <command role=" dongsheng@627: "\"hg-ext-mq\">qpush</command> it again, the changeset that you push will have " dongsheng@627: "a different identity than the changeset you popped." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:321 dongsheng@627: msgid "" dongsheng@627: "The author is the same as the default used by the <command role=\"hg-cmd\">hg " dongsheng@627: "commit</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:325 dongsheng@627: msgid "" dongsheng@627: "The commit message is any text from the patch file that comes before the " dongsheng@627: "first diff header. If there is no such text, a default commit message is " dongsheng@627: "used that identifies the name of the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:330 dongsheng@627: msgid "" dongsheng@627: "If a patch contains a Mercurial patch header (XXX add link), the information " dongsheng@627: "in the patch header overrides these defaults." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:336 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">-a</option>: Push all unapplied " dongsheng@627: "patches from the <filename role=\"special\">series</filename> file until " dongsheng@627: "there are none left to push." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:342 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">-l</option>: Add the name of the " dongsheng@627: "patch to the end of the commit message." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:346 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">-m</option>: If a patch fails to " dongsheng@627: "apply cleanly, use the entry for the patch in another saved queue to compute " dongsheng@627: "the parameters for a three-way merge, and perform a three-way merge using the " dongsheng@627: "normal Mercurial merge machinery. Use the resolution of the merge as the new " dongsheng@627: "patch content." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:354 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">-n</option>: Use the named queue if " dongsheng@627: "merging while pushing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:359 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpush</command> command reads, but does not " dongsheng@627: "modify, the <filename role=\"special\">series</filename> file. It appends " dongsheng@627: "one line to the <command role=\"hg-cmd\">hg status</command> file for each " dongsheng@627: "patch that it pushes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:367 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qrefresh</command>&emdash;update the topmost " dongsheng@627: "applied patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qrefresh</command>&emdash;更新最新的补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:371 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qrefresh</command> command updates the " dongsheng@627: "topmost applied patch. It modifies the patch, removes the old changeset that " dongsheng@627: "represented the patch, and creates a new changeset to represent the modified " dongsheng@627: "patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:377 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qrefresh</command> command looks for the " dongsheng@627: "following modifications:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:380 dongsheng@627: msgid "" dongsheng@627: "Changes to the commit message, i.e. the text before the first diff header in " dongsheng@627: "the patch file, are reflected in the new changeset that represents the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:385 dongsheng@627: msgid "" dongsheng@627: "Modifications to tracked files in the working directory are added to the " dongsheng@627: "patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:388 dongsheng@627: msgid "" dongsheng@627: "Changes to the files tracked using <command role=\"hg-cmd\">hg add</command>, " dongsheng@627: "<command role=\"hg-cmd\">hg copy</command>, <command role=\"hg-cmd\">hg " dongsheng@627: "remove</command>, or <command role=\"hg-cmd\">hg rename</command>. Added " dongsheng@627: "files and copy and rename destinations are added to the patch, while removed " dongsheng@627: "files and rename sources are removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:397 dongsheng@627: msgid "" dongsheng@627: "Even if <command role=\"hg-ext-mq\">qrefresh</command> detects no changes, it " dongsheng@627: "still recreates the changeset that represents the patch. This causes the " dongsheng@627: "identity of the changeset to differ from the previous changeset that " dongsheng@627: "identified the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:405 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-e</option>: Modify the commit " dongsheng@627: "and patch description, using the preferred text editor." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:410 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-m</option>: Modify the commit " dongsheng@627: "message and patch description, using the given text." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:415 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-l</option>: Modify the commit " dongsheng@627: "message and patch description, using text from the given file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:423 dongsheng@627: msgid "<command role=\"hg-ext-mq\">qrename</command>&emdash;rename a patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qrename</command>&emdash;改名补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:426 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qrename</command> command renames a patch, " dongsheng@627: "and changes the entry for the patch in the <filename role=\"special\">series</" dongsheng@627: "filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:430 dongsheng@627: msgid "" dongsheng@627: "With a single argument, <command role=\"hg-ext-mq\">qrename</command> renames " dongsheng@627: "the topmost applied patch. With two arguments, it renames its first argument " dongsheng@627: "to its second." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:437 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qrestore</command>&emdash;restore saved queue " dongsheng@627: "state" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qrestore</command>&emdash;恢复保存的队列" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:441 dongsheng@627: msgid "XXX No idea what this does." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:445 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qsave</command>&emdash;save current queue state" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qsave</command>&emdash;保存当前的队列状态" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:448 dongsheng@627: msgid "XXX Likewise." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:452 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qseries</command>&emdash;print the entire patch " dongsheng@627: "series" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qseries</command>&emdash;显示补丁序列" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:455 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qseries</command> command prints the entire " dongsheng@627: "patch series from the <filename role=\"special\">series</filename> file. It " dongsheng@627: "prints only patch names, not empty lines or comments. It prints in order " dongsheng@627: "from first to be applied to last." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:463 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qtop</command>&emdash;print the name of the " dongsheng@627: "current patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qtop</command>&emdash;显示当前补丁的名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:466 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qtop</command> prints the name of the topmost " dongsheng@627: "currently applied patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:471 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qunapplied</command>&emdash;print patches not yet " dongsheng@627: "applied" dongsheng@627: msgstr "" dongsheng@627: "<command role=\"hg-ext-mq\">qunapplied</command>&emdash;显示尚未应用的补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:475 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qunapplied</command> command prints the names " dongsheng@627: "of patches from the <filename role=\"special\">series</filename> file that " dongsheng@627: "are not yet applied. It prints them in order from the next patch that will " dongsheng@627: "be pushed to the last." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:483 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-cmd\">hg strip</command>&emdash;remove a revision and " dongsheng@627: "descendants" dongsheng@627: msgstr "<command role=\"hg-cmd\">hg strip</command>&emdash;删除一个版本及其后继" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:486 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg strip</command> command removes a revision, " dongsheng@627: "and all of its descendants, from the repository. It undoes the effects of " dongsheng@627: "the removed revisions from the repository, and updates the working directory " dongsheng@627: "to the first parent of the removed revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:492 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg strip</command> command saves a backup of the " dongsheng@627: "removed changesets in a bundle, so that they can be reapplied if removed in " dongsheng@627: "error." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:498 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-opt-strip\">-b</option>: Save unrelated changesets that are " dongsheng@627: "intermixed with the stripped changesets in the backup bundle." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:502 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-opt-strip\">-f</option>: If a branch has multiple heads, " dongsheng@627: "remove all heads. XXX This should be renamed, and use <literal>-f</literal> " dongsheng@627: "to strip revs when there are pending changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:507 dongsheng@627: msgid "<option role=\"hg-opt-strip\">-n</option>: Do not save a backup bundle." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appB-mq-ref.xml:514 dongsheng@627: msgid "MQ file reference" dongsheng@627: msgstr "MQ 文件参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:517 dongsheng@627: msgid "The <filename role=\"special\">series</filename> file" dongsheng@627: msgstr "<filename role=\"special\">序列</filename>文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:520 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">series</filename> file contains a list of the " dongsheng@627: "names of all patches that MQ can apply. It is represented as a list of " dongsheng@627: "names, with one name saved per line. Leading and trailing white space in " dongsheng@627: "each line are ignored." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:526 dongsheng@627: msgid "" dongsheng@627: "Lines may contain comments. A comment begins with the <quote><literal>#</" dongsheng@627: "literal></quote> character, and extends to the end of the line. Empty lines, " dongsheng@627: "and lines that contain only comments, are ignored." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:531 dongsheng@627: msgid "" dongsheng@627: "You will often need to edit the <filename role=\"special\">series</filename> " dongsheng@627: "file by hand, hence the support for comments and empty lines noted above. " dongsheng@627: "For example, you can comment out a patch temporarily, and <command role=\"hg-" dongsheng@627: "ext-mq\">qpush</command> will skip over that patch when applying patches. " dongsheng@627: "You can also change the order in which patches are applied by reordering " dongsheng@627: "their entries in the <filename role=\"special\">series</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:540 dongsheng@627: msgid "" dongsheng@627: "Placing the <filename role=\"special\">series</filename> file under revision " dongsheng@627: "control is also supported; it is a good idea to place all of the patches that " dongsheng@627: "it refers to under revision control, as well. If you create a patch " dongsheng@627: "directory using the <option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option> " dongsheng@627: "option to <command role=\"hg-ext-mq\">qinit</command>, this will be done for " dongsheng@627: "you automatically." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:550 dongsheng@627: msgid "The <filename role=\"special\">status</filename> file" dongsheng@627: msgstr "<filename role=\"special\">状态</filename>文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:553 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">status</filename> file contains the names and " dongsheng@627: "changeset hashes of all patches that MQ currently has applied. Unlike the " dongsheng@627: "<filename role=\"special\">series</filename> file, this file is not intended " dongsheng@627: "for editing. You should not place this file under revision control, or " dongsheng@627: "modify it in any way. It is used by MQ strictly for internal book-keeping." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><title> dongsheng@627: #: ../en/appC-srcinstall.xml:5 dongsheng@627: msgid "Installing Mercurial from source" dongsheng@627: msgstr "从源代码安装 Mercurial" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appC-srcinstall.xml:8 dongsheng@627: msgid "On a Unix-like system" dongsheng@627: msgstr "类 Unix 系统" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:10 dongsheng@627: msgid "" dongsheng@627: "If you are using a Unix-like system that has a sufficiently recent version of " dongsheng@627: "Python (2.3 or newer) available, it is easy to install Mercurial from source." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appC-srcinstall.xml:14 dongsheng@627: msgid "" dongsheng@627: "Download a recent source tarball from <ulink url=\"http://www.selenic.com/" dongsheng@627: "mercurial/download\">http://www.selenic.com/mercurial/download</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appC-srcinstall.xml:17 dongsheng@627: msgid "Unpack the tarball:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appC-srcinstall.xml:20 dongsheng@627: msgid "" dongsheng@627: "Go into the source directory and run the installer script. This will build " dongsheng@627: "Mercurial and install it in your home directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:27 dongsheng@627: msgid "" dongsheng@627: "Once the install finishes, Mercurial will be in the <literal>bin</literal> " dongsheng@627: "subdirectory of your home directory. Don't forget to make sure that this " dongsheng@627: "directory is present in your shell's search path." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:32 dongsheng@627: msgid "" dongsheng@627: "You will probably need to set the <envar>PYTHONPATH</envar> environment " dongsheng@627: "variable so that the Mercurial executable can find the rest of the Mercurial " dongsheng@627: "packages. For example, on my laptop, I have set it to <literal>/home/bos/lib/" dongsheng@627: "python</literal>. The exact path that you will need to use depends on how " dongsheng@627: "Python was built for your system, but should be easy to figure out. If " dongsheng@627: "you're uncertain, look through the output of the installer script above, and " dongsheng@627: "see where the contents of the <literal>mercurial</literal> directory were " dongsheng@627: "installed to." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appC-srcinstall.xml:44 dongsheng@627: msgid "On Windows" dongsheng@627: msgstr "Windows 系统" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:46 dongsheng@627: msgid "" dongsheng@627: "Building and installing Mercurial on Windows requires a variety of tools, a " dongsheng@627: "fair amount of technical knowledge, and considerable patience. I very much " dongsheng@627: "<emphasis>do not recommend</emphasis> this route if you are a <quote>casual " dongsheng@627: "user</quote>. Unless you intend to hack on Mercurial, I strongly suggest " dongsheng@627: "that you use a binary package instead." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:53 dongsheng@627: msgid "" dongsheng@627: "If you are intent on building Mercurial from source on Windows, follow the " dongsheng@627: "<quote>hard way</quote> directions on the Mercurial wiki at <ulink url=" dongsheng@627: "\"http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall\">http://www." dongsheng@627: "selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>, and expect the " dongsheng@627: "process to involve a lot of fiddly work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><title> dongsheng@627: #: ../en/appD-license.xml:5 dongsheng@627: msgid "Open Publication License" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appD-license.xml:7 dongsheng@627: msgid "Version 1.0, 8 June 1999" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:10 dongsheng@627: msgid "Requirements on both unmodified and modified versions" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:13 dongsheng@627: msgid "" dongsheng@627: "The Open Publication works may be reproduced and distributed in whole or in " dongsheng@627: "part, in any medium physical or electronic, provided that the terms of this " dongsheng@627: "license are adhered to, and that this license or an incorporation of it by " dongsheng@627: "reference (with any options elected by the author(s) and/or publisher) is " dongsheng@627: "displayed in the reproduction." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:20 dongsheng@627: msgid "Proper form for an incorporation by reference is as follows:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><blockquote><para> dongsheng@627: #: ../en/appD-license.xml:24 dongsheng@627: msgid "" dongsheng@627: "Copyright (c) <emphasis>year</emphasis> by <emphasis>author's name or " dongsheng@627: "designee</emphasis>. This material may be distributed only subject to the " dongsheng@627: "terms and conditions set forth in the Open Publication License, v<emphasis>x." dongsheng@627: "y</emphasis> or later (the latest version is presently available at <ulink " dongsheng@627: "url=\"http://www.opencontent.org/openpub/\">http://www.opencontent.org/" dongsheng@627: "openpub/</ulink>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:33 dongsheng@627: msgid "" dongsheng@627: "The reference must be immediately followed with any options elected by the " dongsheng@627: "author(s) and/or publisher of the document (see section <xref linkend=\"sec." dongsheng@627: "opl.options\"/>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:37 dongsheng@627: msgid "" dongsheng@627: "Commercial redistribution of Open Publication-licensed material is permitted." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:40 dongsheng@627: msgid "" dongsheng@627: "Any publication in standard (paper) book form shall require the citation of " dongsheng@627: "the original publisher and author. The publisher and author's names shall " dongsheng@627: "appear on all outer surfaces of the book. On all outer surfaces of the book " dongsheng@627: "the original publisher's name shall be as large as the title of the work and " dongsheng@627: "cited as possessive with respect to the title." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:49 dongsheng@627: msgid "Copyright" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:51 dongsheng@627: msgid "" dongsheng@627: "The copyright to each Open Publication is owned by its author(s) or designee." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:56 dongsheng@627: msgid "Scope of license" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:58 dongsheng@627: msgid "" dongsheng@627: "The following license terms apply to all Open Publication works, unless " dongsheng@627: "otherwise explicitly stated in the document." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:62 dongsheng@627: msgid "" dongsheng@627: "Mere aggregation of Open Publication works or a portion of an Open " dongsheng@627: "Publication work with other works or programs on the same media shall not " dongsheng@627: "cause this license to apply to those other works. The aggregate work shall " dongsheng@627: "contain a notice specifying the inclusion of the Open Publication material " dongsheng@627: "and appropriate copyright notice." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:69 dongsheng@627: msgid "" dongsheng@627: "<emphasis role=\"bold\">Severability</emphasis>. If any part of this license " dongsheng@627: "is found to be unenforceable in any jurisdiction, the remaining portions of " dongsheng@627: "the license remain in force." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:74 dongsheng@627: msgid "" dongsheng@627: "<emphasis role=\"bold\">No warranty</emphasis>. Open Publication works are " dongsheng@627: "licensed and provided <quote>as is</quote> without warranty of any kind, " dongsheng@627: "express or implied, including, but not limited to, the implied warranties of " dongsheng@627: "merchantability and fitness for a particular purpose or a warranty of non-" dongsheng@627: "infringement." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:83 dongsheng@627: msgid "Requirements on modified works" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:85 dongsheng@627: msgid "" dongsheng@627: "All modified versions of documents covered by this license, including " dongsheng@627: "translations, anthologies, compilations and partial documents, must meet the " dongsheng@627: "following requirements:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:90 dongsheng@627: msgid "The modified version must be labeled as such." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:93 dongsheng@627: msgid "" dongsheng@627: "The person making the modifications must be identified and the modifications " dongsheng@627: "dated." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:96 dongsheng@627: msgid "" dongsheng@627: "Acknowledgement of the original author and publisher if applicable must be " dongsheng@627: "retained according to normal academic citation practices." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:100 dongsheng@627: msgid "The location of the original unmodified document must be identified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:103 dongsheng@627: msgid "" dongsheng@627: "The original author's (or authors') name(s) may not be used to assert or " dongsheng@627: "imply endorsement of the resulting document without the original author's (or " dongsheng@627: "authors') permission." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:111 dongsheng@627: msgid "Good-practice recommendations" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:113 dongsheng@627: msgid "" dongsheng@627: "In addition to the requirements of this license, it is requested from and " dongsheng@627: "strongly recommended of redistributors that:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:118 dongsheng@627: msgid "" dongsheng@627: "If you are distributing Open Publication works on hardcopy or CD-ROM, you " dongsheng@627: "provide email notification to the authors of your intent to redistribute at " dongsheng@627: "least thirty days before your manuscript or media freeze, to give the authors " dongsheng@627: "time to provide updated documents. This notification should describe " dongsheng@627: "modifications, if any, made to the document." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:125 dongsheng@627: msgid "" dongsheng@627: "All substantive modifications (including deletions) be either clearly marked " dongsheng@627: "up in the document or else described in an attachment to the document." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:129 dongsheng@627: msgid "" dongsheng@627: "Finally, while it is not mandatory under this license, it is considered good " dongsheng@627: "form to offer a free copy of any hardcopy and CD-ROM expression of an Open " dongsheng@627: "Publication-licensed work to its author(s)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:137 dongsheng@627: msgid "License options" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:139 dongsheng@627: msgid "" dongsheng@627: "The author(s) and/or publisher of an Open Publication-licensed document may " dongsheng@627: "elect certain options by appending language to the reference to or copy of " dongsheng@627: "the license. These options are considered part of the license instance and " dongsheng@627: "must be included with the license (or its incorporation by reference) in " dongsheng@627: "derived works." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:147 dongsheng@627: msgid "" dongsheng@627: "To prohibit distribution of substantively modified versions without the " dongsheng@627: "explicit permission of the author(s). <quote>Substantive modification</quote> " dongsheng@627: "is defined as a change to the semantic content of the document, and excludes " dongsheng@627: "mere changes in format or typographical corrections." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:154 dongsheng@627: msgid "" dongsheng@627: "To accomplish this, add the phrase <quote>Distribution of substantively " dongsheng@627: "modified versions of this document is prohibited without the explicit " dongsheng@627: "permission of the copyright holder.</quote> to the license reference or copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:160 dongsheng@627: msgid "" dongsheng@627: "To prohibit any publication of this work or derivative works in whole or in " dongsheng@627: "part in standard (paper) book form for commercial purposes is prohibited " dongsheng@627: "unless prior permission is obtained from the copyright holder." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:165 dongsheng@627: msgid "" dongsheng@627: "To accomplish this, add the phrase <quote>Distribution of the work or " dongsheng@627: "derivative of the work in any standard (paper) book form is prohibited unless " dongsheng@627: "prior permission is obtained from the copyright holder.</quote> to the " dongsheng@627: "license reference or copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch01-intro.xml:5 dongsheng@627: msgid "Introduction" dongsheng@627: msgstr "简介" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:8 dongsheng@627: msgid "About revision control" dongsheng@627: msgstr "关于版本控制" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:10 dongsheng@627: msgid "" dongsheng@627: "Revision control is the process of managing multiple versions of a piece of " dongsheng@627: "information. In its simplest form, this is something that many people do by " dongsheng@627: "hand: every time you modify a file, save it under a new name that contains a " dongsheng@627: "number, each one higher than the number of the preceding version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:16 dongsheng@627: msgid "" dongsheng@627: "Manually managing multiple versions of even a single file is an error-prone " dongsheng@627: "task, though, so software tools to help automate this process have long been " dongsheng@627: "available. The earliest automated revision control tools were intended to " dongsheng@627: "help a single user to manage revisions of a single file. Over the past few " dongsheng@627: "decades, the scope of revision control tools has expanded greatly; they now " dongsheng@627: "manage multiple files, and help multiple people to work together. The best " dongsheng@627: "modern revision control tools have no problem coping with thousands of people " dongsheng@627: "working together on projects that consist of hundreds of thousands of files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:28 dongsheng@627: msgid "Why use revision control?" dongsheng@627: msgstr "为什么使用版本控制?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:30 dongsheng@627: msgid "" dongsheng@627: "There are a number of reasons why you or your team might want to use an " dongsheng@627: "automated revision control tool for a project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:34 dongsheng@627: msgid "" dongsheng@627: "It will track the history and evolution of your project, so you don't have " dongsheng@627: "to. For every change, you'll have a log of <emphasis>who</emphasis> made it; " dongsheng@627: "<emphasis>why</emphasis> they made it; <emphasis>when</emphasis> they made " dongsheng@627: "it; and <emphasis>what</emphasis> the change was." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:41 dongsheng@627: msgid "" dongsheng@627: "When you're working with other people, revision control software makes it " dongsheng@627: "easier for you to collaborate. For example, when people more or less " dongsheng@627: "simultaneously make potentially incompatible changes, the software will help " dongsheng@627: "you to identify and resolve those conflicts." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:47 dongsheng@627: msgid "" dongsheng@627: "It can help you to recover from mistakes. If you make a change that later " dongsheng@627: "turns out to be in error, you can revert to an earlier version of one or more " dongsheng@627: "files. In fact, a <emphasis>really</emphasis> good revision control tool " dongsheng@627: "will even help you to efficiently figure out exactly when a problem was " dongsheng@627: "introduced (see section <xref linkend=\"sec.undo.bisect\"/> for details)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:54 dongsheng@627: msgid "" dongsheng@627: "It will help you to work simultaneously on, and manage the drift between, " dongsheng@627: "multiple versions of your project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:57 dongsheng@627: msgid "" dongsheng@627: "Most of these reasons are equally valid---at least in theory---whether you're " dongsheng@627: "working on a project by yourself, or with a hundred other people." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:61 dongsheng@627: msgid "" dongsheng@627: "A key question about the practicality of revision control at these two " dongsheng@627: "different scales (<quote>lone hacker</quote> and <quote>huge team</quote>) is " dongsheng@627: "how its <emphasis>benefits</emphasis> compare to its <emphasis>costs</" dongsheng@627: "emphasis>. A revision control tool that's difficult to understand or use is " dongsheng@627: "going to impose a high cost." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:69 dongsheng@627: msgid "" dongsheng@627: "A five-hundred-person project is likely to collapse under its own weight " dongsheng@627: "almost immediately without a revision control tool and process. In this case, " dongsheng@627: "the cost of using revision control might hardly seem worth considering, since " dongsheng@627: "<emphasis>without</emphasis> it, failure is almost guaranteed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:76 dongsheng@627: msgid "" dongsheng@627: "On the other hand, a one-person <quote>quick hack</quote> might seem like a " dongsheng@627: "poor place to use a revision control tool, because surely the cost of using " dongsheng@627: "one must be close to the overall cost of the project. Right?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:81 dongsheng@627: msgid "" dongsheng@627: "Mercurial uniquely supports <emphasis>both</emphasis> of these scales of " dongsheng@627: "development. You can learn the basics in just a few minutes, and due to its " dongsheng@627: "low overhead, you can apply revision control to the smallest of projects with " dongsheng@627: "ease. Its simplicity means you won't have a lot of abstruse concepts or " dongsheng@627: "command sequences competing for mental space with whatever you're " dongsheng@627: "<emphasis>really</emphasis> trying to do. At the same time, Mercurial's high " dongsheng@627: "performance and peer-to-peer nature let you scale painlessly to handle large " dongsheng@627: "projects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:91 dongsheng@627: msgid "" dongsheng@627: "No revision control tool can rescue a poorly run project, but a good choice " dongsheng@627: "of tools can make a huge difference to the fluidity with which you can work " dongsheng@627: "on a project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:97 dongsheng@627: msgid "The many names of revision control" dongsheng@627: msgstr "版本控制的别名" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:99 dongsheng@627: msgid "" dongsheng@627: "Revision control is a diverse field, so much so that it doesn't actually have " dongsheng@627: "a single name or acronym. Here are a few of the more common names and " dongsheng@627: "acronyms you'll encounter:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:104 dongsheng@627: msgid "Revision control (RCS)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:105 dongsheng@627: msgid "Software configuration management (SCM), or configuration management" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:107 dongsheng@627: msgid "Source code management" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:108 dongsheng@627: msgid "Source code control, or source control" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:110 dongsheng@627: msgid "Version control (VCS)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:112 dongsheng@627: msgid "" dongsheng@627: "Some people claim that these terms actually have different meanings, but in " dongsheng@627: "practice they overlap so much that there's no agreed or even useful way to " dongsheng@627: "tease them apart." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:119 dongsheng@627: msgid "A short history of revision control" dongsheng@627: msgstr "版本控制简史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:121 dongsheng@627: msgid "" dongsheng@627: "The best known of the old-time revision control tools is SCCS (Source Code " dongsheng@627: "Control System), which Marc Rochkind wrote at Bell Labs, in the early 1970s. " dongsheng@627: "SCCS operated on individual files, and required every person working on a " dongsheng@627: "project to have access to a shared workspace on a single system. Only one " dongsheng@627: "person could modify a file at any time; arbitration for access to files was " dongsheng@627: "via locks. It was common for people to lock files, and later forget to " dongsheng@627: "unlock them, preventing anyone else from modifying those files without the " dongsheng@627: "help of an administrator." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:132 dongsheng@627: msgid "" dongsheng@627: "Walter Tichy developed a free alternative to SCCS in the early 1980s; he " dongsheng@627: "called his program RCS (Revision Control System). Like SCCS, RCS required " dongsheng@627: "developers to work in a single shared workspace, and to lock files to prevent " dongsheng@627: "multiple people from modifying them simultaneously." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:138 dongsheng@627: msgid "" dongsheng@627: "Later in the 1980s, Dick Grune used RCS as a building block for a set of " dongsheng@627: "shell scripts he initially called cmt, but then renamed to CVS (Concurrent " dongsheng@627: "Versions System). The big innovation of CVS was that it let developers work " dongsheng@627: "simultaneously and somewhat independently in their own personal workspaces. " dongsheng@627: "The personal workspaces prevented developers from stepping on each other's " dongsheng@627: "toes all the time, as was common with SCCS and RCS. Each developer had a copy " dongsheng@627: "of every project file, and could modify their copies independently. They had " dongsheng@627: "to merge their edits prior to committing changes to the central repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:149 dongsheng@627: msgid "" dongsheng@627: "Brian Berliner took Grune's original scripts and rewrote them in C, releasing " dongsheng@627: "in 1989 the code that has since developed into the modern version of CVS. " dongsheng@627: "CVS subsequently acquired the ability to operate over a network connection, " dongsheng@627: "giving it a client/server architecture. CVS's architecture is centralised; " dongsheng@627: "only the server has a copy of the history of the project. Client workspaces " dongsheng@627: "just contain copies of recent versions of the project's files, and a little " dongsheng@627: "metadata to tell them where the server is. CVS has been enormously " dongsheng@627: "successful; it is probably the world's most widely used revision control " dongsheng@627: "system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:160 dongsheng@627: msgid "" dongsheng@627: "In the early 1990s, Sun Microsystems developed an early distributed revision " dongsheng@627: "control system, called TeamWare. A TeamWare workspace contains a complete " dongsheng@627: "copy of the project's history. TeamWare has no notion of a central " dongsheng@627: "repository. (CVS relied upon RCS for its history storage; TeamWare used " dongsheng@627: "SCCS.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:167 dongsheng@627: msgid "" dongsheng@627: "As the 1990s progressed, awareness grew of a number of problems with CVS. It " dongsheng@627: "records simultaneous changes to multiple files individually, instead of " dongsheng@627: "grouping them together as a single logically atomic operation. It does not " dongsheng@627: "manage its file hierarchy well; it is easy to make a mess of a repository by " dongsheng@627: "renaming files and directories. Worse, its source code is difficult to read " dongsheng@627: "and maintain, which made the <quote>pain level</quote> of fixing these " dongsheng@627: "architectural problems prohibitive." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:177 dongsheng@627: msgid "" dongsheng@627: "In 2001, Jim Blandy and Karl Fogel, two developers who had worked on CVS, " dongsheng@627: "started a project to replace it with a tool that would have a better " dongsheng@627: "architecture and cleaner code. The result, Subversion, does not stray from " dongsheng@627: "CVS's centralised client/server model, but it adds multi-file atomic commits, " dongsheng@627: "better namespace management, and a number of other features that make it a " dongsheng@627: "generally better tool than CVS. Since its initial release, it has rapidly " dongsheng@627: "grown in popularity." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:186 dongsheng@627: msgid "" dongsheng@627: "More or less simultaneously, Graydon Hoare began working on an ambitious " dongsheng@627: "distributed revision control system that he named Monotone. While Monotone " dongsheng@627: "addresses many of CVS's design flaws and has a peer-to-peer architecture, it " dongsheng@627: "goes beyond earlier (and subsequent) revision control tools in a number of " dongsheng@627: "innovative ways. It uses cryptographic hashes as identifiers, and has an " dongsheng@627: "integral notion of <quote>trust</quote> for code from different sources." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:195 dongsheng@627: msgid "" dongsheng@627: "Mercurial began life in 2005. While a few aspects of its design are " dongsheng@627: "influenced by Monotone, Mercurial focuses on ease of use, high performance, " dongsheng@627: "and scalability to very large projects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:202 dongsheng@627: msgid "Trends in revision control" dongsheng@627: msgstr "版本控制的发展趋势" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:204 dongsheng@627: msgid "" dongsheng@627: "There has been an unmistakable trend in the development and use of revision " dongsheng@627: "control tools over the past four decades, as people have become familiar with " dongsheng@627: "the capabilities of their tools and constrained by their limitations." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:209 dongsheng@627: msgid "" dongsheng@627: "The first generation began by managing single files on individual computers. " dongsheng@627: "Although these tools represented a huge advance over ad-hoc manual revision " dongsheng@627: "control, their locking model and reliance on a single computer limited them " dongsheng@627: "to small, tightly-knit teams." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:215 dongsheng@627: msgid "" dongsheng@627: "The second generation loosened these constraints by moving to network-" dongsheng@627: "centered architectures, and managing entire projects at a time. As projects " dongsheng@627: "grew larger, they ran into new problems. With clients needing to talk to " dongsheng@627: "servers very frequently, server scaling became an issue for large projects. " dongsheng@627: "An unreliable network connection could prevent remote users from being able " dongsheng@627: "to talk to the server at all. As open source projects started making read-" dongsheng@627: "only access available anonymously to anyone, people without commit privileges " dongsheng@627: "found that they could not use the tools to interact with a project in a " dongsheng@627: "natural way, as they could not record their changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:227 dongsheng@627: msgid "" dongsheng@627: "The current generation of revision control tools is peer-to-peer in nature. " dongsheng@627: "All of these systems have dropped the dependency on a single central server, " dongsheng@627: "and allow people to distribute their revision control data to where it's " dongsheng@627: "actually needed. Collaboration over the Internet has moved from constrained " dongsheng@627: "by technology to a matter of choice and consensus. Modern tools can operate " dongsheng@627: "offline indefinitely and autonomously, with a network connection only needed " dongsheng@627: "when syncing changes with another repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:239 dongsheng@627: msgid "A few of the advantages of distributed revision control" dongsheng@627: msgstr "分布版本控制的优点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:242 dongsheng@627: msgid "" dongsheng@627: "Even though distributed revision control tools have for several years been as " dongsheng@627: "robust and usable as their previous-generation counterparts, people using " dongsheng@627: "older tools have not yet necessarily woken up to their advantages. There are " dongsheng@627: "a number of ways in which distributed tools shine relative to centralised " dongsheng@627: "ones." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:249 dongsheng@627: msgid "" dongsheng@627: "For an individual developer, distributed tools are almost always much faster " dongsheng@627: "than centralised tools. This is for a simple reason: a centralised tool " dongsheng@627: "needs to talk over the network for many common operations, because most " dongsheng@627: "metadata is stored in a single copy on the central server. A distributed " dongsheng@627: "tool stores all of its metadata locally. All else being equal, talking over " dongsheng@627: "the network adds overhead to a centralised tool. Don't underestimate the " dongsheng@627: "value of a snappy, responsive tool: you're going to spend a lot of time " dongsheng@627: "interacting with your revision control software." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:260 dongsheng@627: msgid "" dongsheng@627: "Distributed tools are indifferent to the vagaries of your server " dongsheng@627: "infrastructure, again because they replicate metadata to so many locations. " dongsheng@627: "If you use a centralised system and your server catches fire, you'd better " dongsheng@627: "hope that your backup media are reliable, and that your last backup was " dongsheng@627: "recent and actually worked. With a distributed tool, you have many backups " dongsheng@627: "available on every contributor's computer." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:268 dongsheng@627: msgid "" dongsheng@627: "The reliability of your network will affect distributed tools far less than " dongsheng@627: "it will centralised tools. You can't even use a centralised tool without a " dongsheng@627: "network connection, except for a few highly constrained commands. With a " dongsheng@627: "distributed tool, if your network connection goes down while you're working, " dongsheng@627: "you may not even notice. The only thing you won't be able to do is talk to " dongsheng@627: "repositories on other computers, something that is relatively rare compared " dongsheng@627: "with local operations. If you have a far-flung team of collaborators, this " dongsheng@627: "may be significant." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:279 dongsheng@627: msgid "Advantages for open source projects" dongsheng@627: msgstr "开源项目的优点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:281 dongsheng@627: msgid "" dongsheng@627: "If you take a shine to an open source project and decide that you would like " dongsheng@627: "to start hacking on it, and that project uses a distributed revision control " dongsheng@627: "tool, you are at once a peer with the people who consider themselves the " dongsheng@627: "<quote>core</quote> of that project. If they publish their repositories, you " dongsheng@627: "can immediately copy their project history, start making changes, and record " dongsheng@627: "your work, using the same tools in the same ways as insiders. By contrast, " dongsheng@627: "with a centralised tool, you must use the software in a <quote>read only</" dongsheng@627: "quote> mode unless someone grants you permission to commit changes to their " dongsheng@627: "central server. Until then, you won't be able to record changes, and your " dongsheng@627: "local modifications will be at risk of corruption any time you try to update " dongsheng@627: "your client's view of the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch01-intro.xml:297 dongsheng@627: msgid "The forking non-problem" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:299 dongsheng@627: msgid "" dongsheng@627: "It has been suggested that distributed revision control tools pose some sort " dongsheng@627: "of risk to open source projects because they make it easy to <quote>fork</" dongsheng@627: "quote> the development of a project. A fork happens when there are " dongsheng@627: "differences in opinion or attitude between groups of developers that cause " dongsheng@627: "them to decide that they can't work together any longer. Each side takes a " dongsheng@627: "more or less complete copy of the project's source code, and goes off in its " dongsheng@627: "own direction." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:309 dongsheng@627: msgid "" dongsheng@627: "Sometimes the camps in a fork decide to reconcile their differences. With a " dongsheng@627: "centralised revision control system, the <emphasis>technical</emphasis> " dongsheng@627: "process of reconciliation is painful, and has to be performed largely by " dongsheng@627: "hand. You have to decide whose revision history is going to <quote>win</" dongsheng@627: "quote>, and graft the other team's changes into the tree somehow. This " dongsheng@627: "usually loses some or all of one side's revision history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:318 dongsheng@627: msgid "" dongsheng@627: "What distributed tools do with respect to forking is they make forking the " dongsheng@627: "<emphasis>only</emphasis> way to develop a project. Every single change that " dongsheng@627: "you make is potentially a fork point. The great strength of this approach is " dongsheng@627: "that a distributed revision control tool has to be really good at " dongsheng@627: "<emphasis>merging</emphasis> forks, because forks are absolutely fundamental: " dongsheng@627: "they happen all the time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:327 dongsheng@627: msgid "" dongsheng@627: "If every piece of work that everybody does, all the time, is framed in terms " dongsheng@627: "of forking and merging, then what the open source world refers to as a " dongsheng@627: "<quote>fork</quote> becomes <emphasis>purely</emphasis> a social issue. If " dongsheng@627: "anything, distributed tools <emphasis>lower</emphasis> the likelihood of a " dongsheng@627: "fork:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:334 dongsheng@627: msgid "" dongsheng@627: "They eliminate the social distinction that centralised tools impose: that " dongsheng@627: "between insiders (people with commit access) and outsiders (people without)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:338 dongsheng@627: msgid "" dongsheng@627: "They make it easier to reconcile after a social fork, because all that's " dongsheng@627: "involved from the perspective of the revision control software is just " dongsheng@627: "another merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:343 dongsheng@627: msgid "" dongsheng@627: "Some people resist distributed tools because they want to retain tight " dongsheng@627: "control over their projects, and they believe that centralised tools give " dongsheng@627: "them this control. However, if you're of this belief, and you publish your " dongsheng@627: "CVS or Subversion repositories publicly, there are plenty of tools available " dongsheng@627: "that can pull out your entire project's history (albeit slowly) and recreate " dongsheng@627: "it somewhere that you don't control. So while your control in this case is " dongsheng@627: "illusory, you are forgoing the ability to fluidly collaborate with whatever " dongsheng@627: "people feel compelled to mirror and fork your history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:358 dongsheng@627: msgid "Advantages for commercial projects" dongsheng@627: msgstr "商业项目的优点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:360 dongsheng@627: msgid "" dongsheng@627: "Many commercial projects are undertaken by teams that are scattered across " dongsheng@627: "the globe. Contributors who are far from a central server will see slower " dongsheng@627: "command execution and perhaps less reliability. Commercial revision control " dongsheng@627: "systems attempt to ameliorate these problems with remote-site replication add-" dongsheng@627: "ons that are typically expensive to buy and cantankerous to administer. A " dongsheng@627: "distributed system doesn't suffer from these problems in the first place. " dongsheng@627: "Better yet, you can easily set up multiple authoritative servers, say one per " dongsheng@627: "site, so that there's no redundant communication between repositories over " dongsheng@627: "expensive long-haul network links." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:372 dongsheng@627: msgid "" dongsheng@627: "Centralised revision control systems tend to have relatively low " dongsheng@627: "scalability. It's not unusual for an expensive centralised system to fall " dongsheng@627: "over under the combined load of just a few dozen concurrent users. Once " dongsheng@627: "again, the typical response tends to be an expensive and clunky replication " dongsheng@627: "facility. Since the load on a central server---if you have one at all---is " dongsheng@627: "many times lower with a distributed tool (because all of the data is " dongsheng@627: "replicated everywhere), a single cheap server can handle the needs of a much " dongsheng@627: "larger team, and replication to balance load becomes a simple matter of " dongsheng@627: "scripting." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:384 dongsheng@627: msgid "" dongsheng@627: "If you have an employee in the field, troubleshooting a problem at a " dongsheng@627: "customer's site, they'll benefit from distributed revision control. The tool " dongsheng@627: "will let them generate custom builds, try different fixes in isolation from " dongsheng@627: "each other, and search efficiently through history for the sources of bugs " dongsheng@627: "and regressions in the customer's environment, all without needing to connect " dongsheng@627: "to your company's network." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:395 dongsheng@627: msgid "Why choose Mercurial?" dongsheng@627: msgstr "为什么选择 Mercurial?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:397 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a unique set of properties that make it a particularly good " dongsheng@627: "choice as a revision control system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:400 dongsheng@627: msgid "It is easy to learn and use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:401 dongsheng@627: msgid "It is lightweight." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:402 dongsheng@627: msgid "It scales excellently." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:403 dongsheng@627: msgid "It is easy to customise." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:406 dongsheng@627: msgid "" dongsheng@627: "If you are at all familiar with revision control systems, you should be able " dongsheng@627: "to get up and running with Mercurial in less than five minutes. Even if not, " dongsheng@627: "it will take no more than a few minutes longer. Mercurial's command and " dongsheng@627: "feature sets are generally uniform and consistent, so you can keep track of a " dongsheng@627: "few general rules instead of a host of exceptions." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:413 dongsheng@627: msgid "" dongsheng@627: "On a small project, you can start working with Mercurial in moments. Creating " dongsheng@627: "new changes and branches; transferring changes around (whether locally or " dongsheng@627: "over a network); and history and status operations are all fast. Mercurial " dongsheng@627: "attempts to stay nimble and largely out of your way by combining low " dongsheng@627: "cognitive overhead with blazingly fast operations." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:420 dongsheng@627: msgid "" dongsheng@627: "The usefulness of Mercurial is not limited to small projects: it is used by " dongsheng@627: "projects with hundreds to thousands of contributors, each containing tens of " dongsheng@627: "thousands of files and hundreds of megabytes of source code." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:425 dongsheng@627: msgid "" dongsheng@627: "If the core functionality of Mercurial is not enough for you, it's easy to " dongsheng@627: "build on. Mercurial is well suited to scripting tasks, and its clean " dongsheng@627: "internals and implementation in Python make it easy to add features in the " dongsheng@627: "form of extensions. There are a number of popular and useful extensions " dongsheng@627: "already available, ranging from helping to identify bugs to improving " dongsheng@627: "performance." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:435 dongsheng@627: msgid "Mercurial compared with other tools" dongsheng@627: msgstr "Mercurial 与其它工具的比较" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:437 dongsheng@627: msgid "" dongsheng@627: "Before you read on, please understand that this section necessarily reflects " dongsheng@627: "my own experiences, interests, and (dare I say it) biases. I have used every " dongsheng@627: "one of the revision control tools listed below, in most cases for several " dongsheng@627: "years at a time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:445 ../en/ch01-intro.xml:656 dongsheng@627: msgid "Subversion" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:447 dongsheng@627: msgid "" dongsheng@627: "Subversion is a popular revision control tool, developed to replace CVS. It " dongsheng@627: "has a centralised client/server architecture." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:451 dongsheng@627: msgid "" dongsheng@627: "Subversion and Mercurial have similarly named commands for performing the " dongsheng@627: "same operations, so if you're familiar with one, it is easy to learn to use " dongsheng@627: "the other. Both tools are portable to all popular operating systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:456 dongsheng@627: msgid "" dongsheng@627: "Prior to version 1.5, Subversion had no useful support for merges. At the " dongsheng@627: "time of writing, its merge tracking capability is new, and known to be <ulink " dongsheng@627: "url=\"http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced." dongsheng@627: "html#svn.branchmerge.advanced.finalword\">complicated and buggy</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:462 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a substantial performance advantage over Subversion on every " dongsheng@627: "revision control operation I have benchmarked. I have measured its advantage " dongsheng@627: "as ranging from a factor of two to a factor of six when compared with " dongsheng@627: "Subversion 1.4.3's <emphasis>ra_local</emphasis> file store, which is the " dongsheng@627: "fastest access method available. In more realistic deployments involving a " dongsheng@627: "network-based store, Subversion will be at a substantially larger " dongsheng@627: "disadvantage. Because many Subversion commands must talk to the server and " dongsheng@627: "Subversion does not have useful replication facilities, server capacity and " dongsheng@627: "network bandwidth become bottlenecks for modestly large projects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:475 dongsheng@627: msgid "" dongsheng@627: "Additionally, Subversion incurs substantial storage overhead to avoid network " dongsheng@627: "transactions for a few common operations, such as finding modified files " dongsheng@627: "(<literal>status</literal>) and displaying modifications against the current " dongsheng@627: "revision (<literal>diff</literal>). As a result, a Subversion working copy " dongsheng@627: "is often the same size as, or larger than, a Mercurial repository and working " dongsheng@627: "directory, even though the Mercurial repository contains a complete history " dongsheng@627: "of the project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:485 dongsheng@627: msgid "" dongsheng@627: "Subversion is widely supported by third party tools. Mercurial currently " dongsheng@627: "lags considerably in this area. This gap is closing, however, and indeed " dongsheng@627: "some of Mercurial's GUI tools now outshine their Subversion equivalents. " dongsheng@627: "Like Mercurial, Subversion has an excellent user manual." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:491 dongsheng@627: msgid "" dongsheng@627: "Because Subversion doesn't store revision history on the client, it is well " dongsheng@627: "suited to managing projects that deal with lots of large, opaque binary " dongsheng@627: "files. If you check in fifty revisions to an incompressible 10MB file, " dongsheng@627: "Subversion's client-side space usage stays constant The space used by any " dongsheng@627: "distributed SCM will grow rapidly in proportion to the number of revisions, " dongsheng@627: "because the differences between each revision are large." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:500 dongsheng@627: msgid "" dongsheng@627: "In addition, it's often difficult or, more usually, impossible to merge " dongsheng@627: "different versions of a binary file. Subversion's ability to let a user lock " dongsheng@627: "a file, so that they temporarily have the exclusive right to commit changes " dongsheng@627: "to it, can be a significant advantage to a project where binary files are " dongsheng@627: "widely used." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:507 dongsheng@627: msgid "" dongsheng@627: "Mercurial can import revision history from a Subversion repository. It can " dongsheng@627: "also export revision history to a Subversion repository. This makes it easy " dongsheng@627: "to <quote>test the waters</quote> and use Mercurial and Subversion in " dongsheng@627: "parallel before deciding to switch. History conversion is incremental, so " dongsheng@627: "you can perform an initial conversion, then small additional conversions " dongsheng@627: "afterwards to bring in new changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:519 ../en/ch01-intro.xml:658 dongsheng@627: msgid "Git" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:521 dongsheng@627: msgid "" dongsheng@627: "Git is a distributed revision control tool that was developed for managing " dongsheng@627: "the Linux kernel source tree. Like Mercurial, its early design was somewhat " dongsheng@627: "influenced by Monotone." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:526 dongsheng@627: msgid "" dongsheng@627: "Git has a very large command set, with version 1.5.0 providing 139 individual " dongsheng@627: "commands. It has something of a reputation for being difficult to learn. " dongsheng@627: "Compared to Git, Mercurial has a strong focus on simplicity." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:531 dongsheng@627: msgid "" dongsheng@627: "In terms of performance, Git is extremely fast. In several cases, it is " dongsheng@627: "faster than Mercurial, at least on Linux, while Mercurial performs better on " dongsheng@627: "other operations. However, on Windows, the performance and general level of " dongsheng@627: "support that Git provides is, at the time of writing, far behind that of " dongsheng@627: "Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:538 dongsheng@627: msgid "" dongsheng@627: "While a Mercurial repository needs no maintenance, a Git repository requires " dongsheng@627: "frequent manual <quote>repacks</quote> of its metadata. Without these, " dongsheng@627: "performance degrades, while space usage grows rapidly. A server that " dongsheng@627: "contains many Git repositories that are not rigorously and frequently " dongsheng@627: "repacked will become heavily disk-bound during backups, and there have been " dongsheng@627: "instances of daily backups taking far longer than 24 hours as a result. A " dongsheng@627: "freshly packed Git repository is slightly smaller than a Mercurial " dongsheng@627: "repository, but an unpacked repository is several orders of magnitude larger." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:549 dongsheng@627: msgid "" dongsheng@627: "The core of Git is written in C. Many Git commands are implemented as shell " dongsheng@627: "or Perl scripts, and the quality of these scripts varies widely. I have " dongsheng@627: "encountered several instances where scripts charged along blindly in the " dongsheng@627: "presence of errors that should have been fatal." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:555 dongsheng@627: msgid "Mercurial can import revision history from a Git repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:561 ../en/ch01-intro.xml:657 dongsheng@627: msgid "CVS" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:563 dongsheng@627: msgid "" dongsheng@627: "CVS is probably the most widely used revision control tool in the world. Due " dongsheng@627: "to its age and internal untidiness, it has been only lightly maintained for " dongsheng@627: "many years." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:567 dongsheng@627: msgid "" dongsheng@627: "It has a centralised client/server architecture. It does not group related " dongsheng@627: "file changes into atomic commits, making it easy for people to <quote>break " dongsheng@627: "the build</quote>: one person can successfully commit part of a change and " dongsheng@627: "then be blocked by the need for a merge, causing other people to see only a " dongsheng@627: "portion of the work they intended to do. This also affects how you work with " dongsheng@627: "project history. If you want to see all of the modifications someone made as " dongsheng@627: "part of a task, you will need to manually inspect the descriptions and " dongsheng@627: "timestamps of the changes made to each file involved (if you even know what " dongsheng@627: "those files were)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:579 dongsheng@627: msgid "" dongsheng@627: "CVS has a muddled notion of tags and branches that I will not attempt to even " dongsheng@627: "describe. It does not support renaming of files or directories well, making " dongsheng@627: "it easy to corrupt a repository. It has almost no internal consistency " dongsheng@627: "checking capabilities, so it is usually not even possible to tell whether or " dongsheng@627: "how a repository is corrupt. I would not recommend CVS for any project, " dongsheng@627: "existing or new." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:587 dongsheng@627: msgid "" dongsheng@627: "Mercurial can import CVS revision history. However, there are a few caveats " dongsheng@627: "that apply; these are true of every other revision control tool's CVS " dongsheng@627: "importer, too. Due to CVS's lack of atomic changes and unversioned " dongsheng@627: "filesystem hierarchy, it is not possible to reconstruct CVS history " dongsheng@627: "completely accurately; some guesswork is involved, and renames will usually " dongsheng@627: "not show up. Because a lot of advanced CVS administration has to be done by " dongsheng@627: "hand and is hence error-prone, it's common for CVS importers to run into " dongsheng@627: "multiple problems with corrupted repositories (completely bogus revision " dongsheng@627: "timestamps and files that have remained locked for over a decade are just two " dongsheng@627: "of the less interesting problems I can recall from personal experience)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:601 dongsheng@627: msgid "Mercurial can import revision history from a CVS repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:607 dongsheng@627: msgid "Commercial tools" dongsheng@627: msgstr "商业工具" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:609 dongsheng@627: msgid "" dongsheng@627: "Perforce has a centralised client/server architecture, with no client-side " dongsheng@627: "caching of any data. Unlike modern revision control tools, Perforce requires " dongsheng@627: "that a user run a command to inform the server about every file they intend " dongsheng@627: "to edit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:615 dongsheng@627: msgid "" dongsheng@627: "The performance of Perforce is quite good for small teams, but it falls off " dongsheng@627: "rapidly as the number of users grows beyond a few dozen. Modestly large " dongsheng@627: "Perforce installations require the deployment of proxies to cope with the " dongsheng@627: "load their users generate." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:624 dongsheng@627: msgid "Choosing a revision control tool" dongsheng@627: msgstr "选择版本控制工具" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:626 dongsheng@627: msgid "" dongsheng@627: "With the exception of CVS, all of the tools listed above have unique " dongsheng@627: "strengths that suit them to particular styles of work. There is no single " dongsheng@627: "revision control tool that is best in all situations." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:631 dongsheng@627: msgid "" dongsheng@627: "As an example, Subversion is a good choice for working with frequently edited " dongsheng@627: "binary files, due to its centralised nature and support for file locking." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:635 dongsheng@627: msgid "" dongsheng@627: "I personally find Mercurial's properties of simplicity, performance, and good " dongsheng@627: "merge support to be a compelling combination that has served me well for " dongsheng@627: "several years." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:643 dongsheng@627: msgid "Switching from another tool to Mercurial" dongsheng@627: msgstr "从其它工具切换到 Mercurial" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:645 dongsheng@627: msgid "" dongsheng@627: "Mercurial is bundled with an extension named <literal role=\"hg-ext" dongsheng@627: "\">convert</literal>, which can incrementally import revision history from " dongsheng@627: "several other revision control tools. By <quote>incremental</quote>, I mean " dongsheng@627: "that you can convert all of a project's history to date in one go, then rerun " dongsheng@627: "the conversion later to obtain new changes that happened after the initial " dongsheng@627: "conversion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:653 dongsheng@627: msgid "" dongsheng@627: "The revision control tools supported by <literal role=\"hg-ext\">convert</" dongsheng@627: "literal> are as follows:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:659 dongsheng@627: msgid "Darcs" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:661 dongsheng@627: msgid "" dongsheng@627: "In addition, <literal role=\"hg-ext\">convert</literal> can export changes " dongsheng@627: "from Mercurial to Subversion. This makes it possible to try Subversion and " dongsheng@627: "Mercurial in parallel before committing to a switchover, without risking the " dongsheng@627: "loss of any work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:667 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-conver\">convert</command> command is easy to " dongsheng@627: "use. Simply point it at the path or URL of the source repository, optionally " dongsheng@627: "give it the name of the destination repository, and it will start working. " dongsheng@627: "After the initial conversion, just run the same command again to import new " dongsheng@627: "changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:5 dongsheng@627: msgid "A tour of Mercurial: the basics" dongsheng@627: msgstr "Mercurial 教程: 基础知识" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:8 dongsheng@627: msgid "Installing Mercurial on your system" dongsheng@627: msgstr "安装 Mercurial" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:10 dongsheng@627: msgid "" dongsheng@627: "Prebuilt binary packages of Mercurial are available for every popular " dongsheng@627: "operating system. These make it easy to start using Mercurial on your " dongsheng@627: "computer immediately." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:15 dongsheng@627: msgid "Linux" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:17 dongsheng@627: msgid "" dongsheng@627: "Because each Linux distribution has its own packaging tools, policies, and " dongsheng@627: "rate of development, it's difficult to give a comprehensive set of " dongsheng@627: "instructions on how to install Mercurial binaries. The version of Mercurial " dongsheng@627: "that you will end up with can vary depending on how active the person is who " dongsheng@627: "maintains the package for your distribution." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:24 dongsheng@627: msgid "" dongsheng@627: "To keep things simple, I will focus on installing Mercurial from the command " dongsheng@627: "line under the most popular Linux distributions. Most of these distributions " dongsheng@627: "provide graphical package managers that will let you install Mercurial with a " dongsheng@627: "single click; the package name to look for is <literal>mercurial</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:32 dongsheng@627: msgid "Debian:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:35 dongsheng@627: msgid "Fedora Core:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:38 dongsheng@627: msgid "Gentoo:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:40 dongsheng@627: msgid "OpenSUSE:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:43 dongsheng@627: msgid "" dongsheng@627: "Ubuntu: Ubuntu's Mercurial package is based on Debian's. To install it, run " dongsheng@627: "the following command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:52 dongsheng@627: msgid "Solaris" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:54 dongsheng@627: msgid "" dongsheng@627: "SunFreeWare, at <ulink url=\"http://www.sunfreeware.com\">http://www." dongsheng@627: "sunfreeware.com</ulink>, is a good source for a large number of pre-built " dongsheng@627: "Solaris packages for 32 and 64 bit Intel and Sparc architectures, including " dongsheng@627: "current versions of Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:62 dongsheng@627: msgid "Mac OS X" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:64 dongsheng@627: msgid "" dongsheng@627: "Lee Cantey publishes an installer of Mercurial for Mac OS X at <ulink url=" dongsheng@627: "\"http://mercurial.berkwood.com\">http://mercurial.berkwood.com</ulink>. " dongsheng@627: "This package works on both Intel- and Power-based Macs. Before you can use " dongsheng@627: "it, you must install a compatible version of Universal MacPython " dongsheng@627: "<citation>web:macpython</citation>. This is easy to do; simply follow the " dongsheng@627: "instructions on Lee's site." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:73 dongsheng@627: msgid "" dongsheng@627: "It's also possible to install Mercurial using Fink or MacPorts, two popular " dongsheng@627: "free package managers for Mac OS X. If you have Fink, use <command>sudo apt-" dongsheng@627: "get install mercurial-py25</command>. If MacPorts, <command>sudo port " dongsheng@627: "install mercurial</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:81 dongsheng@627: msgid "Windows" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:83 dongsheng@627: msgid "" dongsheng@627: "Lee Cantey publishes an installer of Mercurial for Windows at <ulink url=" dongsheng@627: "\"http://mercurial.berkwood.com\">http://mercurial.berkwood.com</ulink>. " dongsheng@627: "This package has no external dependencies; it <quote>just works</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:90 dongsheng@627: msgid "" dongsheng@627: "The Windows version of Mercurial does not automatically convert line endings " dongsheng@627: "between Windows and Unix styles. If you want to share work with Unix users, " dongsheng@627: "you must do a little additional configuration work. XXX Flesh this out." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:100 dongsheng@627: msgid "Getting started" dongsheng@627: msgstr "开始" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:102 dongsheng@627: msgid "" dongsheng@627: "To begin, we'll use the <command role=\"hg-cmd\">hg version</command> command " dongsheng@627: "to find out whether Mercurial is actually installed properly. The actual " dongsheng@627: "version information that it prints isn't so important; it's whether it prints " dongsheng@627: "anything at all that we care about." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:111 dongsheng@627: msgid "Built-in help" dongsheng@627: msgstr "内置帮助" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:113 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides a built-in help system. This is invaluable for those " dongsheng@627: "times when you find yourself stuck trying to remember how to run a command. " dongsheng@627: "If you are completely stuck, simply run <command role=\"hg-cmd\">hg help</" dongsheng@627: "command>; it will print a brief list of commands, along with a description of " dongsheng@627: "what each does. If you ask for help on a specific command (as below), it " dongsheng@627: "prints more detailed information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:124 dongsheng@627: msgid "" dongsheng@627: "For a more impressive level of detail (which you won't usually need) run " dongsheng@627: "<command role=\"hg-cmd\">hg help <option role=\"hg-opt-global\">-v</option></" dongsheng@627: "command>. The <option role=\"hg-opt-global\">-v</option> option is short for " dongsheng@627: "<option role=\"hg-opt-global\">--verbose</option>, and tells Mercurial to " dongsheng@627: "print more information than it usually would." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:135 dongsheng@627: msgid "Working with a repository" dongsheng@627: msgstr "使用版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:137 dongsheng@627: msgid "" dongsheng@627: "In Mercurial, everything happens inside a <emphasis>repository</emphasis>. " dongsheng@627: "The repository for a project contains all of the files that <quote>belong to</" dongsheng@627: "quote> that project, along with a historical record of the project's files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:143 dongsheng@627: msgid "" dongsheng@627: "There's nothing particularly magical about a repository; it is simply a " dongsheng@627: "directory tree in your filesystem that Mercurial treats as special. You can " dongsheng@627: "rename or delete a repository any time you like, using either the command " dongsheng@627: "line or your file browser." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:150 dongsheng@627: msgid "Making a local copy of a repository" dongsheng@627: msgstr "创建版本库的工作副本" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:152 dongsheng@627: msgid "" dongsheng@627: "<emphasis>Copying</emphasis> a repository is just a little bit special. " dongsheng@627: "While you could use a normal file copying command to make a copy of a " dongsheng@627: "repository, it's best to use a built-in command that Mercurial provides. " dongsheng@627: "This command is called <command role=\"hg-cmd\">hg clone</command>, because " dongsheng@627: "it creates an identical copy of an existing repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:161 dongsheng@627: msgid "" dongsheng@627: "If our clone succeeded, we should now have a local directory called <filename " dongsheng@627: "class=\"directory\">hello</filename>. This directory will contain some files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:167 dongsheng@627: msgid "" dongsheng@627: "These files have the same contents and history in our repository as they do " dongsheng@627: "in the repository we cloned." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:170 dongsheng@627: msgid "" dongsheng@627: "Every Mercurial repository is complete, self-contained, and independent. It " dongsheng@627: "contains its own private copy of a project's files and history. A cloned " dongsheng@627: "repository remembers the location of the repository it was cloned from, but " dongsheng@627: "it does not communicate with that repository, or any other, unless you tell " dongsheng@627: "it to." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:177 dongsheng@627: msgid "" dongsheng@627: "What this means for now is that we're free to experiment with our repository, " dongsheng@627: "safe in the knowledge that it's a private <quote>sandbox</quote> that won't " dongsheng@627: "affect anyone else." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:183 dongsheng@627: msgid "What's in a repository?" dongsheng@627: msgstr "什么是版本库?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:185 dongsheng@627: msgid "" dongsheng@627: "When we take a more detailed look inside a repository, we can see that it " dongsheng@627: "contains a directory named <filename class=\"directory\">.hg</filename>. " dongsheng@627: "This is where Mercurial keeps all of its metadata for the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:192 dongsheng@627: msgid "" dongsheng@627: "The contents of the <filename class=\"directory\">.hg</filename> directory " dongsheng@627: "and its subdirectories are private to Mercurial. Every other file and " dongsheng@627: "directory in the repository is yours to do with as you please." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:198 dongsheng@627: msgid "" dongsheng@627: "To introduce a little terminology, the <filename class=\"directory\">.hg</" dongsheng@627: "filename> directory is the <quote>real</quote> repository, and all of the " dongsheng@627: "files and directories that coexist with it are said to live in the " dongsheng@627: "<emphasis>working directory</emphasis>. An easy way to remember the " dongsheng@627: "distinction is that the <emphasis>repository</emphasis> contains the " dongsheng@627: "<emphasis>history</emphasis> of your project, while the <emphasis>working " dongsheng@627: "directory</emphasis> contains a <emphasis>snapshot</emphasis> of your project " dongsheng@627: "at a particular point in history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:213 dongsheng@627: msgid "A tour through history" dongsheng@627: msgstr "回溯历史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:215 dongsheng@627: msgid "" dongsheng@627: "One of the first things we might want to do with a new, unfamiliar repository " dongsheng@627: "is understand its history. The <command role=\"hg-cmd\">hg log</command> " dongsheng@627: "command gives us a view of history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:222 dongsheng@627: msgid "" dongsheng@627: "By default, this command prints a brief paragraph of output for each change " dongsheng@627: "to the project that was recorded. In Mercurial terminology, we call each of " dongsheng@627: "these recorded events a <emphasis>changeset</emphasis>, because it can " dongsheng@627: "contain a record of changes to several files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:228 dongsheng@627: msgid "" dongsheng@627: "The fields in a record of output from <command role=\"hg-cmd\">hg log</" dongsheng@627: "command> are as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:231 dongsheng@627: msgid "" dongsheng@627: "<literal>changeset</literal>: This field has the format of a number, followed " dongsheng@627: "by a colon, followed by a hexadecimal string. These are " dongsheng@627: "<emphasis>identifiers</emphasis> for the changeset. There are two " dongsheng@627: "identifiers because the number is shorter and easier to type than the hex " dongsheng@627: "string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:237 dongsheng@627: msgid "" dongsheng@627: "<literal>user</literal>: The identity of the person who created the " dongsheng@627: "changeset. This is a free-form field, but it most often contains a person's " dongsheng@627: "name and email address." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:241 dongsheng@627: msgid "" dongsheng@627: "<literal>date</literal>: The date and time on which the changeset was " dongsheng@627: "created, and the timezone in which it was created. (The date and time are " dongsheng@627: "local to that timezone; they display what time and date it was for the person " dongsheng@627: "who created the changeset.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:246 dongsheng@627: msgid "" dongsheng@627: "<literal>summary</literal>: The first line of the text message that the " dongsheng@627: "creator of the changeset entered to describe the changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:249 dongsheng@627: msgid "" dongsheng@627: "The default output printed by <command role=\"hg-cmd\">hg log</command> is " dongsheng@627: "purely a summary; it is missing a lot of detail." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:253 dongsheng@627: msgid "" dongsheng@627: "Figure <xref linkend=\"fig.tour-basic.history\"/> provides a graphical " dongsheng@627: "representation of the history of the <filename class=\"directory\">hello</" dongsheng@627: "filename> repository, to make it a little easier to see which direction " dongsheng@627: "history is <quote>flowing</quote> in. We'll be returning to this figure " dongsheng@627: "several times in this chapter and the chapter that follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject> dongsheng@627: #: ../en/ch02-tour-basic.xml:263 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-history.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><textobject><phrase> dongsheng@627: #: ../en/ch02-tour-basic.xml:264 ../en/ch03-tour-merge.xml:48 dongsheng@627: #: ../en/ch03-tour-merge.xml:76 ../en/ch03-tour-merge.xml:124 dongsheng@627: #: ../en/ch03-tour-merge.xml:181 ../en/ch03-tour-merge.xml:248 dongsheng@627: #: ../en/ch04-concepts.xml:54 ../en/ch04-concepts.xml:104 dongsheng@627: #: ../en/ch04-concepts.xml:189 ../en/ch04-concepts.xml:293 dongsheng@627: #: ../en/ch04-concepts.xml:342 ../en/ch04-concepts.xml:356 dongsheng@627: #: ../en/ch04-concepts.xml:396 ../en/ch04-concepts.xml:415 dongsheng@627: #: ../en/ch04-concepts.xml:456 ../en/ch06-collab.xml:275 dongsheng@627: #: ../en/ch09-undo.xml:363 ../en/ch09-undo.xml:411 ../en/ch09-undo.xml:476 dongsheng@627: #: ../en/ch09-undo.xml:516 ../en/ch12-mq.xml:408 dongsheng@627: msgid "XXX add text" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:265 dongsheng@627: msgid "" dongsheng@627: "Graphical history of the <filename class=\"directory\">hello</filename> " dongsheng@627: "repository" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:272 dongsheng@627: msgid "Changesets, revisions, and talking to other people" dongsheng@627: msgstr "改变集，版本，与其它用户交互" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:275 dongsheng@627: msgid "" dongsheng@627: "As English is a notoriously sloppy language, and computer science has a " dongsheng@627: "hallowed history of terminological confusion (why use one term when four will " dongsheng@627: "do?), revision control has a variety of words and phrases that mean the same " dongsheng@627: "thing. If you are talking about Mercurial history with other people, you " dongsheng@627: "will find that the word <quote>changeset</quote> is often compressed to " dongsheng@627: "<quote>change</quote> or (when written) <quote>cset</quote>, and sometimes a " dongsheng@627: "changeset is referred to as a <quote>revision</quote> or a <quote>rev</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:285 dongsheng@627: msgid "" dongsheng@627: "While it doesn't matter what <emphasis>word</emphasis> you use to refer to " dongsheng@627: "the concept of <quote>a changeset</quote>, the <emphasis>identifier</" dongsheng@627: "emphasis> that you use to refer to <quote>a <emphasis>specific</emphasis> " dongsheng@627: "changeset</quote> is of great importance. Recall that the <literal>changeset</" dongsheng@627: "literal> field in the output from <command role=\"hg-cmd\">hg log</command> " dongsheng@627: "identifies a changeset using both a number and a hexadecimal string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:294 dongsheng@627: msgid "" dongsheng@627: "The revision number is <emphasis>only valid in that repository</emphasis>," dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:296 dongsheng@627: msgid "" dongsheng@627: "while the hex string is the <emphasis>permanent, unchanging identifier</" dongsheng@627: "emphasis> that will always identify that exact changeset in <emphasis>every</" dongsheng@627: "emphasis> copy of the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:301 dongsheng@627: msgid "" dongsheng@627: "This distinction is important. If you send someone an email talking about " dongsheng@627: "<quote>revision 33</quote>, there's a high likelihood that their revision 33 " dongsheng@627: "will <emphasis>not be the same</emphasis> as yours. The reason for this is " dongsheng@627: "that a revision number depends on the order in which changes arrived in a " dongsheng@627: "repository, and there is no guarantee that the same changes will happen in " dongsheng@627: "the same order in different repositories. Three changes $a,b,c$ can easily " dongsheng@627: "appear in one repository as $0,1,2$, while in another as $1,0,2$." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:311 dongsheng@627: msgid "" dongsheng@627: "Mercurial uses revision numbers purely as a convenient shorthand. If you " dongsheng@627: "need to discuss a changeset with someone, or make a record of a changeset for " dongsheng@627: "some other reason (for example, in a bug report), use the hexadecimal " dongsheng@627: "identifier." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:319 dongsheng@627: msgid "Viewing specific revisions" dongsheng@627: msgstr "察看指定版本" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:321 dongsheng@627: msgid "" dongsheng@627: "To narrow the output of <command role=\"hg-cmd\">hg log</command> down to a " dongsheng@627: "single revision, use the <option role=\"hg-opt-log\">-r</option> (or <option " dongsheng@627: "role=\"hg-opt-log\">--rev</option>) option. You can use either a revision " dongsheng@627: "number or a long-form changeset identifier, and you can provide as many " dongsheng@627: "revisions as you want." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:330 dongsheng@627: msgid "" dongsheng@627: "If you want to see the history of several revisions without having to list " dongsheng@627: "each one, you can use <emphasis>range notation</emphasis>; this lets you " dongsheng@627: "express the idea <quote>I want all revisions between <literal>abc</literal> " dongsheng@627: "and <literal>def</literal>, inclusive</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:338 dongsheng@627: msgid "" dongsheng@627: "Mercurial also honours the order in which you specify revisions, so <command " dongsheng@627: "role=\"hg-cmd\">hg log -r 2:4</command> prints 2, 3, and 4. while <command " dongsheng@627: "role=\"hg-cmd\">hg log -r 4:2</command> prints 4, 3, and 2." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:345 dongsheng@627: msgid "More detailed information" dongsheng@627: msgstr "更详细的信息" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:347 dongsheng@627: msgid "" dongsheng@627: "While the summary information printed by <command role=\"hg-cmd\">hg log</" dongsheng@627: "command> is useful if you already know what you're looking for, you may need " dongsheng@627: "to see a complete description of the change, or a list of the files changed, " dongsheng@627: "if you're trying to decide whether a changeset is the one you're looking for. " dongsheng@627: "The <command role=\"hg-cmd\">hg log</command> command's <option role=\"hg-opt-" dongsheng@627: "global\">-v</option> (or <option role=\"hg-opt-global\">--verbose</option>) " dongsheng@627: "option gives you this extra detail." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:359 dongsheng@627: msgid "" dongsheng@627: "If you want to see both the description and content of a change, add the " dongsheng@627: "<option role=\"hg-opt-log\">-p</option> (or <option role=\"hg-opt-log\">--" dongsheng@627: "patch</option>) option. This displays the content of a change as a " dongsheng@627: "<emphasis>unified diff</emphasis> (if you've never seen a unified diff " dongsheng@627: "before, see section <xref linkend=\"sec.mq.patch\"/> for an overview)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:372 dongsheng@627: msgid "All about command options" dongsheng@627: msgstr "命令选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:374 dongsheng@627: msgid "" dongsheng@627: "Let's take a brief break from exploring Mercurial commands to discuss a " dongsheng@627: "pattern in the way that they work; you may find this useful to keep in mind " dongsheng@627: "as we continue our tour." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:378 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a consistent and straightforward approach to dealing with the " dongsheng@627: "options that you can pass to commands. It follows the conventions for " dongsheng@627: "options that are common to modern Linux and Unix systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:383 dongsheng@627: msgid "" dongsheng@627: "Every option has a long name. For example, as we've already seen, the " dongsheng@627: "<command role=\"hg-cmd\">hg log</command> command accepts a <option role=\"hg-" dongsheng@627: "opt-log\">--rev</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:387 dongsheng@627: msgid "" dongsheng@627: "Most options have short names, too. Instead of <option role=\"hg-opt-log\">--" dongsheng@627: "rev</option>, we can use <option role=\"hg-opt-log\">-r</option>. (The " dongsheng@627: "reason that some options don't have short names is that the options in " dongsheng@627: "question are rarely used.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:392 dongsheng@627: msgid "" dongsheng@627: "Long options start with two dashes (e.g. <option role=\"hg-opt-log\">--rev</" dongsheng@627: "option>), while short options start with one (e.g. <option role=\"hg-opt-log" dongsheng@627: "\">-r</option>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:396 dongsheng@627: msgid "" dongsheng@627: "Option naming and usage is consistent across commands. For example, every " dongsheng@627: "command that lets you specify a changeset ID or revision number accepts both " dongsheng@627: "<option role=\"hg-opt-log\">-r</option> and <option role=\"hg-opt-log\">--" dongsheng@627: "rev</option> arguments." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:402 dongsheng@627: msgid "" dongsheng@627: "In the examples throughout this book, I use short options instead of long. " dongsheng@627: "This just reflects my own preference, so don't read anything significant into " dongsheng@627: "it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:406 dongsheng@627: msgid "" dongsheng@627: "Most commands that print output of some kind will print more output when " dongsheng@627: "passed a <option role=\"hg-opt-global\">-v</option> (or <option role=\"hg-opt-" dongsheng@627: "global\">--verbose</option>) option, and less when passed <option role=\"hg-" dongsheng@627: "opt-global\">-q</option> (or <option role=\"hg-opt-global\">--quiet</option>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:414 dongsheng@627: msgid "Making and reviewing changes" dongsheng@627: msgstr "创建和复审修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:416 dongsheng@627: msgid "" dongsheng@627: "Now that we have a grasp of viewing history in Mercurial, let's take a look " dongsheng@627: "at making some changes and examining them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:420 dongsheng@627: msgid "" dongsheng@627: "The first thing we'll do is isolate our experiment in a repository of its " dongsheng@627: "own. We use the <command role=\"hg-cmd\">hg clone</command> command, but we " dongsheng@627: "don't need to clone a copy of the remote repository. Since we already have a " dongsheng@627: "copy of it locally, we can just clone that instead. This is much faster than " dongsheng@627: "cloning over the network, and cloning a local repository uses less disk space " dongsheng@627: "in most cases, too." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:430 dongsheng@627: msgid "" dongsheng@627: "As an aside, it's often good practice to keep a <quote>pristine</quote> copy " dongsheng@627: "of a remote repository around, which you can then make temporary clones of to " dongsheng@627: "create sandboxes for each task you want to work on. This lets you work on " dongsheng@627: "multiple tasks in parallel, each isolated from the others until it's complete " dongsheng@627: "and you're ready to integrate it back. Because local clones are so cheap, " dongsheng@627: "there's almost no overhead to cloning and destroying repositories whenever " dongsheng@627: "you want." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:439 dongsheng@627: msgid "" dongsheng@627: "In our <filename class=\"directory\">my-hello</filename> repository, we have " dongsheng@627: "a file <filename>hello.c</filename> that contains the classic <quote>hello, " dongsheng@627: "world</quote> program. Let's use the ancient and venerable <command>sed</" dongsheng@627: "command> command to edit this file so that it prints a second line of " dongsheng@627: "output. (I'm only using <command>sed</command> to do this because it's easy " dongsheng@627: "to write a scripted example this way. Since you're not under the same " dongsheng@627: "constraint, you probably won't want to use <command>sed</command>; simply use " dongsheng@627: "your preferred text editor to do the same thing.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:452 dongsheng@627: msgid "" dongsheng@627: "Mercurial's <command role=\"hg-cmd\">hg status</command> command will tell us " dongsheng@627: "what Mercurial knows about the files in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:458 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg status</command> command prints no output for " dongsheng@627: "some files, but a line starting with <quote><literal>M</literal></quote> for " dongsheng@627: "<filename>hello.c</filename>. Unless you tell it to, <command role=\"hg-cmd" dongsheng@627: "\">hg status</command> will not print any output for files that have not been " dongsheng@627: "modified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:465 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>M</literal></quote> indicates that Mercurial has noticed " dongsheng@627: "that we modified <filename>hello.c</filename>. We didn't need to " dongsheng@627: "<emphasis>inform</emphasis> Mercurial that we were going to modify the file " dongsheng@627: "before we started, or that we had modified the file after we were done; it " dongsheng@627: "was able to figure this out itself." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:473 dongsheng@627: msgid "" dongsheng@627: "It's a little bit helpful to know that we've modified <filename>hello.c</" dongsheng@627: "filename>, but we might prefer to know exactly <emphasis>what</emphasis> " dongsheng@627: "changes we've made to it. To do this, we use the <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:483 dongsheng@627: msgid "Recording changes in a new changeset" dongsheng@627: msgstr "在新修改集中记录修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:485 dongsheng@627: msgid "" dongsheng@627: "We can modify files, build and test our changes, and use <command role=\"hg-" dongsheng@627: "cmd\">hg status</command> and <command role=\"hg-cmd\">hg diff</command> to " dongsheng@627: "review our changes, until we're satisfied with what we've done and arrive at " dongsheng@627: "a natural stopping point where we want to record our work in a new changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:492 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg commit</command> command lets us create a new " dongsheng@627: "changeset; we'll usually refer to this as <quote>making a commit</quote> or " dongsheng@627: "<quote>committing</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:498 dongsheng@627: msgid "Setting up a username" dongsheng@627: msgstr "配置用户名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:500 dongsheng@627: msgid "" dongsheng@627: "When you try to run <command role=\"hg-cmd\">hg commit</command> for the " dongsheng@627: "first time, it is not guaranteed to succeed. Mercurial records your name and " dongsheng@627: "address with each change that you commit, so that you and others will later " dongsheng@627: "be able to tell who made each change. Mercurial tries to automatically " dongsheng@627: "figure out a sensible username to commit the change with. It will attempt " dongsheng@627: "each of the following methods, in order:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:509 dongsheng@627: msgid "" dongsheng@627: "If you specify a <option role=\"hg-opt-commit\">-u</option> option to the " dongsheng@627: "<command role=\"hg-cmd\">hg commit</command> command on the command line, " dongsheng@627: "followed by a username, this is always given the highest precedence." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:514 dongsheng@627: msgid "" dongsheng@627: "If you have set the <envar>HGUSER</envar> environment variable, this is " dongsheng@627: "checked next." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:517 dongsheng@627: msgid "" dongsheng@627: "If you create a file in your home directory called <filename role=\"special" dongsheng@627: "\">.hgrc</filename>, with a <envar role=\"rc-item-ui\">username</envar> " dongsheng@627: "entry, that will be used next. To see what the contents of this file should " dongsheng@627: "look like, refer to section <xref linkend=\"sec.tour-basic.username\"/> below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:524 dongsheng@627: msgid "" dongsheng@627: "If you have set the <envar>EMAIL</envar> environment variable, this will be " dongsheng@627: "used next." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:527 dongsheng@627: msgid "" dongsheng@627: "Mercurial will query your system to find out your local user name and host " dongsheng@627: "name, and construct a username from these components. Since this often " dongsheng@627: "results in a username that is not very useful, it will print a warning if it " dongsheng@627: "has to do this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:534 dongsheng@627: msgid "" dongsheng@627: "If all of these mechanisms fail, Mercurial will fail, printing an error " dongsheng@627: "message. In this case, it will not let you commit until you set up a " dongsheng@627: "username." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:538 dongsheng@627: msgid "" dongsheng@627: "You should think of the <envar>HGUSER</envar> environment variable and the " dongsheng@627: "<option role=\"hg-opt-commit\">-u</option> option to the <command role=\"hg-" dongsheng@627: "cmd\">hg commit</command> command as ways to <emphasis>override</emphasis> " dongsheng@627: "Mercurial's default selection of username. For normal use, the simplest and " dongsheng@627: "most robust way to set a username for yourself is by creating a <filename " dongsheng@627: "role=\"special\">.hgrc</filename> file; see below for details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:547 dongsheng@627: msgid "Creating a Mercurial configuration file" dongsheng@627: msgstr "创建 Mercurial 的配置文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:549 dongsheng@627: msgid "" dongsheng@627: "To set a user name, use your favourite editor to create a file called " dongsheng@627: "<filename role=\"special\">.hgrc</filename> in your home directory. " dongsheng@627: "Mercurial will use this file to look up your personalised configuration " dongsheng@627: "settings. The initial contents of your <filename role=\"special\">.hgrc</" dongsheng@627: "filename> should look like this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:560 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>[ui]</literal></quote> line begins a <emphasis>section</" dongsheng@627: "emphasis> of the config file, so you can read the <quote><literal>username " dongsheng@627: "= ...</literal></quote> line as meaning <quote>set the value of the " dongsheng@627: "<literal>username</literal> item in the <literal>ui</literal> section</" dongsheng@627: "quote>. A section continues until a new section begins, or the end of the " dongsheng@627: "file. Mercurial ignores empty lines and treats any text from " dongsheng@627: "<quote><literal>#</literal></quote> to the end of a line as a comment." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:573 dongsheng@627: msgid "Choosing a user name" dongsheng@627: msgstr "选择用户名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:575 dongsheng@627: msgid "" dongsheng@627: "You can use any text you like as the value of the <literal>username</literal> " dongsheng@627: "config item, since this information is for reading by other people, but for " dongsheng@627: "interpreting by Mercurial. The convention that most people follow is to use " dongsheng@627: "their name and email address, as in the example above." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><note><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:582 dongsheng@627: msgid "" dongsheng@627: "Mercurial's built-in web server obfuscates email addresses, to make it more " dongsheng@627: "difficult for the email harvesting tools that spammers use. This reduces the " dongsheng@627: "likelihood that you'll start receiving more junk email if you publish a " dongsheng@627: "Mercurial repository on the web." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:592 dongsheng@627: msgid "Writing a commit message" dongsheng@627: msgstr "写提交日志" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:594 dongsheng@627: msgid "" dongsheng@627: "When we commit a change, Mercurial drops us into a text editor, to enter a " dongsheng@627: "message that will describe the modifications we've made in this changeset. " dongsheng@627: "This is called the <emphasis>commit message</emphasis>. It will be a record " dongsheng@627: "for readers of what we did and why, and it will be printed by <command role=" dongsheng@627: "\"hg-cmd\">hg log</command> after we've finished committing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:604 dongsheng@627: msgid "" dongsheng@627: "The editor that the <command role=\"hg-cmd\">hg commit</command> command " dongsheng@627: "drops us into will contain an empty line, followed by a number of lines " dongsheng@627: "starting with <quote><literal>HG:</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:611 dongsheng@627: msgid "" dongsheng@627: "Mercurial ignores the lines that start with <quote><literal>HG:</literal></" dongsheng@627: "quote>; it uses them only to tell us which files it's recording changes to. " dongsheng@627: "Modifying or deleting these lines has no effect." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:617 dongsheng@627: msgid "Writing a good commit message" dongsheng@627: msgstr "写好提交日志" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:619 dongsheng@627: msgid "" dongsheng@627: "Since <command role=\"hg-cmd\">hg log</command> only prints the first line of " dongsheng@627: "a commit message by default, it's best to write a commit message whose first " dongsheng@627: "line stands alone. Here's a real example of a commit message that " dongsheng@627: "<emphasis>doesn't</emphasis> follow this guideline, and hence has a summary " dongsheng@627: "that is not readable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:633 dongsheng@627: msgid "" dongsheng@627: "As far as the remainder of the contents of the commit message are concerned, " dongsheng@627: "there are no hard-and-fast rules. Mercurial itself doesn't interpret or care " dongsheng@627: "about the contents of the commit message, though your project may have " dongsheng@627: "policies that dictate a certain kind of formatting." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:639 dongsheng@627: msgid "" dongsheng@627: "My personal preference is for short, but informative, commit messages that " dongsheng@627: "tell me something that I can't figure out with a quick glance at the output " dongsheng@627: "of <command role=\"hg-cmd\">hg log --patch</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:646 dongsheng@627: msgid "Aborting a commit" dongsheng@627: msgstr "终止提交" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:648 dongsheng@627: msgid "" dongsheng@627: "If you decide that you don't want to commit while in the middle of editing a " dongsheng@627: "commit message, simply exit from your editor without saving the file that " dongsheng@627: "it's editing. This will cause nothing to happen to either the repository or " dongsheng@627: "the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:653 dongsheng@627: msgid "" dongsheng@627: "If we run the <command role=\"hg-cmd\">hg commit</command> command without " dongsheng@627: "any arguments, it records all of the changes we've made, as reported by " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> and <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:660 dongsheng@627: msgid "Admiring our new handiwork" dongsheng@627: msgstr "欣赏我们的新手艺" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:662 dongsheng@627: msgid "" dongsheng@627: "Once we've finished the commit, we can use the <command role=\"hg-cmd\">hg " dongsheng@627: "tip</command> command to display the changeset we just created. This command " dongsheng@627: "produces output that is identical to <command role=\"hg-cmd\">hg log</" dongsheng@627: "command>, but it only displays the newest revision in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:671 dongsheng@627: msgid "" dongsheng@627: "We refer to the newest revision in the repository as the tip revision, or " dongsheng@627: "simply the tip." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:678 dongsheng@627: msgid "Sharing changes" dongsheng@627: msgstr "共享修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:680 dongsheng@627: msgid "" dongsheng@627: "We mentioned earlier that repositories in Mercurial are self-contained. This " dongsheng@627: "means that the changeset we just created exists only in our <filename class=" dongsheng@627: "\"directory\">my-hello</filename> repository. Let's look at a few ways that " dongsheng@627: "we can propagate this change into other repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:688 dongsheng@627: msgid "Pulling changes from another repository" dongsheng@627: msgstr "从其它版本库取得修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:689 dongsheng@627: msgid "" dongsheng@627: "To get started, let's clone our original <filename class=\"directory\">hello</" dongsheng@627: "filename> repository, which does not contain the change we just committed. " dongsheng@627: "We'll call our temporary repository <filename class=\"directory\">hello-pull</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:697 dongsheng@627: msgid "" dongsheng@627: "We'll use the <command role=\"hg-cmd\">hg pull</command> command to bring " dongsheng@627: "changes from <filename class=\"directory\">my-hello</filename> into <filename " dongsheng@627: "class=\"directory\">hello-pull</filename>. However, blindly pulling unknown " dongsheng@627: "changes into a repository is a somewhat scary prospect. Mercurial provides " dongsheng@627: "the <command role=\"hg-cmd\">hg incoming</command> command to tell us what " dongsheng@627: "changes the <command role=\"hg-cmd\">hg pull</command> command " dongsheng@627: "<emphasis>would</emphasis> pull into the repository, without actually pulling " dongsheng@627: "the changes in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:710 dongsheng@627: msgid "" dongsheng@627: "(Of course, someone could cause more changesets to appear in the repository " dongsheng@627: "that we ran <command role=\"hg-cmd\">hg incoming</command> in, before we get " dongsheng@627: "a chance to <command role=\"hg-cmd\">hg pull</command> the changes, so that " dongsheng@627: "we could end up pulling changes that we didn't expect.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:717 dongsheng@627: msgid "" dongsheng@627: "Bringing changes into a repository is a simple matter of running the <command " dongsheng@627: "role=\"hg-cmd\">hg pull</command> command, and telling it which repository to " dongsheng@627: "pull from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:724 dongsheng@627: msgid "" dongsheng@627: "As you can see from the before-and-after output of <command role=\"hg-cmd" dongsheng@627: "\">hg tip</command>, we have successfully pulled changes into our " dongsheng@627: "repository. There remains one step before we can see these changes in the " dongsheng@627: "working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:732 dongsheng@627: msgid "Updating the working directory" dongsheng@627: msgstr "更新工作目录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:734 dongsheng@627: msgid "" dongsheng@627: "We have so far glossed over the relationship between a repository and its " dongsheng@627: "working directory. The <command role=\"hg-cmd\">hg pull</command> command " dongsheng@627: "that we ran in section <xref linkend=\"sec.tour.pull\"/> brought changes into " dongsheng@627: "the repository, but if we check, there's no sign of those changes in the " dongsheng@627: "working directory. This is because <command role=\"hg-cmd\">hg pull</" dongsheng@627: "command> does not (by default) touch the working directory. Instead, we use " dongsheng@627: "the <command role=\"hg-cmd\">hg update</command> command to do this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:746 dongsheng@627: msgid "" dongsheng@627: "It might seem a bit strange that <command role=\"hg-cmd\">hg pull</command> " dongsheng@627: "doesn't update the working directory automatically. There's actually a good " dongsheng@627: "reason for this: you can use <command role=\"hg-cmd\">hg update</command> to " dongsheng@627: "update the working directory to the state it was in at <emphasis>any " dongsheng@627: "revision</emphasis> in the history of the repository. If you had the working " dongsheng@627: "directory updated to an old revision---to hunt down the origin of a bug, " dongsheng@627: "say---and ran a <command role=\"hg-cmd\">hg pull</command> which " dongsheng@627: "automatically updated the working directory to a new revision, you might not " dongsheng@627: "be terribly happy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:757 dongsheng@627: msgid "" dongsheng@627: "However, since pull-then-update is such a common thing to do, Mercurial lets " dongsheng@627: "you combine the two by passing the <option role=\"hg-opt-pull\">-u</option> " dongsheng@627: "option to <command role=\"hg-cmd\">hg pull</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:762 dongsheng@627: msgid "" dongsheng@627: "If you look back at the output of <command role=\"hg-cmd\">hg pull</command> " dongsheng@627: "in section <xref linkend=\"sec.tour.pull\"/> when we ran it without <option " dongsheng@627: "role=\"hg-opt-pull\">-u</option>, you can see that it printed a helpful " dongsheng@627: "reminder that we'd have to take an explicit step to update the working " dongsheng@627: "directory:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:771 dongsheng@627: msgid "" dongsheng@627: "To find out what revision the working directory is at, use the <command role=" dongsheng@627: "\"hg-cmd\">hg parents</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:777 dongsheng@627: msgid "" dongsheng@627: "If you look back at figure <xref linkend=\"fig.tour-basic.history\"/>, you'll " dongsheng@627: "see arrows connecting each changeset. The node that the arrow leads " dongsheng@627: "<emphasis>from</emphasis> in each case is a parent, and the node that the " dongsheng@627: "arrow leads <emphasis>to</emphasis> is its child. The working directory has " dongsheng@627: "a parent in just the same way; this is the changeset that the working " dongsheng@627: "directory currently contains." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:786 dongsheng@627: msgid "" dongsheng@627: "To update the working directory to a particular revision, give a revision " dongsheng@627: "number or changeset ID to the <command role=\"hg-cmd\">hg update</command> " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:793 dongsheng@627: msgid "" dongsheng@627: "If you omit an explicit revision, <command role=\"hg-cmd\">hg update</" dongsheng@627: "command> will update to the tip revision, as shown by the second call to " dongsheng@627: "<command role=\"hg-cmd\">hg update</command> in the example above." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:801 dongsheng@627: msgid "Pushing changes to another repository" dongsheng@627: msgstr "发布修改到其它版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:803 dongsheng@627: msgid "" dongsheng@627: "Mercurial lets us push changes to another repository, from the repository " dongsheng@627: "we're currently visiting. As with the example of <command role=\"hg-cmd\">hg " dongsheng@627: "pull</command> above, we'll create a temporary repository to push our changes " dongsheng@627: "into." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:811 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg outgoing</command> command tells us what " dongsheng@627: "changes would be pushed into another repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:817 dongsheng@627: msgid "" dongsheng@627: "And the <command role=\"hg-cmd\">hg push</command> command does the actual " dongsheng@627: "push." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:823 dongsheng@627: msgid "" dongsheng@627: "As with <command role=\"hg-cmd\">hg pull</command>, the <command role=\"hg-cmd" dongsheng@627: "\">hg push</command> command does not update the working directory in the " dongsheng@627: "repository that it's pushing changes into. (Unlike <command role=\"hg-cmd" dongsheng@627: "\">hg pull</command>, <command role=\"hg-cmd\">hg push</command> does not " dongsheng@627: "provide a <literal>-u</literal> option that updates the other repository's " dongsheng@627: "working directory.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:832 dongsheng@627: msgid "" dongsheng@627: "What happens if we try to pull or push changes and the receiving repository " dongsheng@627: "already has those changes? Nothing too exciting." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:839 dongsheng@627: msgid "Sharing changes over a network" dongsheng@627: msgstr "通过网络共享修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:841 dongsheng@627: msgid "" dongsheng@627: "The commands we have covered in the previous few sections are not limited to " dongsheng@627: "working with local repositories. Each works in exactly the same fashion over " dongsheng@627: "a network connection; simply pass in a URL instead of a local path." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:849 dongsheng@627: msgid "" dongsheng@627: "In this example, we can see what changes we could push to the remote " dongsheng@627: "repository, but the repository is understandably not set up to let anonymous " dongsheng@627: "users push to it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:5 dongsheng@627: msgid "A tour of Mercurial: merging work" dongsheng@627: msgstr "Mercurial 教程: 合并工作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:7 dongsheng@627: msgid "" dongsheng@627: "We've now covered cloning a repository, making changes in a repository, and " dongsheng@627: "pulling or pushing changes from one repository into another. Our next step " dongsheng@627: "is <emphasis>merging</emphasis> changes from separate repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:13 dongsheng@627: msgid "Merging streams of work" dongsheng@627: msgstr "合并的流程" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:15 dongsheng@627: msgid "" dongsheng@627: "Merging is a fundamental part of working with a distributed revision control " dongsheng@627: "tool." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:18 dongsheng@627: msgid "" dongsheng@627: "Alice and Bob each have a personal copy of a repository for a project they're " dongsheng@627: "collaborating on. Alice fixes a bug in her repository; Bob adds a new " dongsheng@627: "feature in his. They want the shared repository to contain both the bug fix " dongsheng@627: "and the new feature." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:24 dongsheng@627: msgid "" dongsheng@627: "I frequently work on several different tasks for a single project at once, " dongsheng@627: "each safely isolated in its own repository. Working this way means that I " dongsheng@627: "often need to merge one piece of my own work with another." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:30 dongsheng@627: msgid "" dongsheng@627: "Because merging is such a common thing to need to do, Mercurial makes it " dongsheng@627: "easy. Let's walk through the process. We'll begin by cloning yet another " dongsheng@627: "repository (see how often they spring up?) and making a change in it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:37 dongsheng@627: msgid "" dongsheng@627: "We should now have two copies of <filename>hello.c</filename> with different " dongsheng@627: "contents. The histories of the two repositories have also diverged, as " dongsheng@627: "illustrated in figure <xref linkend=\"fig.tour-merge.sep-repos\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:47 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-merge-sep-repos.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:49 dongsheng@627: msgid "" dongsheng@627: "Divergent recent histories of the <filename class=\"directory\">my-hello</" dongsheng@627: "filename> and <filename class=\"directory\">my-new-hello</filename> " dongsheng@627: "repositories" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:56 dongsheng@627: msgid "" dongsheng@627: "We already know that pulling changes from our <filename class=\"directory" dongsheng@627: "\">my-hello</filename> repository will have no effect on the working " dongsheng@627: "directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:62 dongsheng@627: msgid "" dongsheng@627: "However, the <command role=\"hg-cmd\">hg pull</command> command says " dongsheng@627: "something about <quote>heads</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:66 dongsheng@627: msgid "Head changesets" dongsheng@627: msgstr "顶点改变集" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:68 dongsheng@627: msgid "" dongsheng@627: "A head is a change that has no descendants, or children, as they're also " dongsheng@627: "known. The tip revision is thus a head, because the newest revision in a " dongsheng@627: "repository doesn't have any children, but a repository can contain more than " dongsheng@627: "one head." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:75 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-merge-pull.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:78 dongsheng@627: msgid "" dongsheng@627: "Repository contents after pulling from <filename class=\"directory\">my-" dongsheng@627: "hello</filename> into <filename class=\"directory\">my-new-hello</filename>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:85 dongsheng@627: msgid "" dongsheng@627: "In figure <xref linkend=\"fig.tour-merge.pull\"/>, you can see the effect of " dongsheng@627: "the pull from <filename class=\"directory\">my-hello</filename> into " dongsheng@627: "<filename class=\"directory\">my-new-hello</filename>. The history that was " dongsheng@627: "already present in <filename class=\"directory\">my-new-hello</filename> is " dongsheng@627: "untouched, but a new revision has been added. By referring to figure <xref " dongsheng@627: "linkend=\"fig.tour-merge.sep-repos\"/>, we can see that the " dongsheng@627: "<emphasis>changeset ID</emphasis> remains the same in the new repository, but " dongsheng@627: "the <emphasis>revision number</emphasis> has changed. (This, incidentally, " dongsheng@627: "is a fine example of why it's not safe to use revision numbers when " dongsheng@627: "discussing changesets.) We can view the heads in a repository using the " dongsheng@627: "<command role=\"hg-cmd\">hg heads</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:104 dongsheng@627: msgid "Performing the merge" dongsheng@627: msgstr "执行合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:106 dongsheng@627: msgid "" dongsheng@627: "What happens if we try to use the normal <command role=\"hg-cmd\">hg update</" dongsheng@627: "command> command to update to the new tip?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:112 dongsheng@627: msgid "" dongsheng@627: "Mercurial is telling us that the <command role=\"hg-cmd\">hg update</command> " dongsheng@627: "command won't do a merge; it won't update the working directory when it " dongsheng@627: "thinks we might be wanting to do a merge, unless we force it to do so. " dongsheng@627: "Instead, we use the <command role=\"hg-cmd\">hg merge</command> command to " dongsheng@627: "merge the two heads." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:123 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-merge-merge.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:126 dongsheng@627: msgid "Working directory and repository during merge, and following commit" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:131 dongsheng@627: msgid "" dongsheng@627: "This updates the working directory so that it contains changes from " dongsheng@627: "<emphasis>both</emphasis> heads, which is reflected in both the output of " dongsheng@627: "<command role=\"hg-cmd\">hg parents</command> and the contents of " dongsheng@627: "<filename>hello.c</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:141 dongsheng@627: msgid "Committing the results of the merge" dongsheng@627: msgstr "提交合并结果" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:143 dongsheng@627: msgid "" dongsheng@627: "Whenever we've done a merge, <command role=\"hg-cmd\">hg parents</command> " dongsheng@627: "will display two parents until we <command role=\"hg-cmd\">hg commit</" dongsheng@627: "command> the results of the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:150 dongsheng@627: msgid "" dongsheng@627: "We now have a new tip revision; notice that it has <emphasis>both</emphasis> " dongsheng@627: "of our former heads as its parents. These are the same revisions that were " dongsheng@627: "previously displayed by <command role=\"hg-cmd\">hg parents</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:157 dongsheng@627: msgid "" dongsheng@627: "In figure <xref linkend=\"fig.tour-merge.merge\"/>, you can see a " dongsheng@627: "representation of what happens to the working directory during the merge, and " dongsheng@627: "how this affects the repository when the commit happens. During the merge, " dongsheng@627: "the working directory has two parent changesets, and these become the parents " dongsheng@627: "of the new changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:168 dongsheng@627: msgid "Merging conflicting changes" dongsheng@627: msgstr "合并有冲突的改变" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:170 dongsheng@627: msgid "" dongsheng@627: "Most merges are simple affairs, but sometimes you'll find yourself merging " dongsheng@627: "changes where each modifies the same portions of the same files. Unless both " dongsheng@627: "modifications are identical, this results in a <emphasis>conflict</emphasis>, " dongsheng@627: "where you have to decide how to reconcile the different changes into " dongsheng@627: "something coherent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:180 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-merge-conflict.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:182 dongsheng@627: msgid "Conflicting changes to a document" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:186 dongsheng@627: msgid "" dongsheng@627: "Figure <xref linkend=\"fig.tour-merge.conflict\"/> illustrates an instance of " dongsheng@627: "two conflicting changes to a document. We started with a single version of " dongsheng@627: "the file; then we made some changes; while someone else made different " dongsheng@627: "changes to the same text. Our task in resolving the conflicting changes is " dongsheng@627: "to decide what the file should look like." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:193 dongsheng@627: msgid "" dongsheng@627: "Mercurial doesn't have a built-in facility for handling conflicts. Instead, " dongsheng@627: "it runs an external program called <command>hgmerge</command>. This is a " dongsheng@627: "shell script that is bundled with Mercurial; you can change it to behave " dongsheng@627: "however you please. What it does by default is try to find one of several " dongsheng@627: "different merging tools that are likely to be installed on your system. It " dongsheng@627: "first tries a few fully automatic merging tools; if these don't succeed " dongsheng@627: "(because the resolution process requires human guidance) or aren't present, " dongsheng@627: "the script tries a few different graphical merging tools." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:204 dongsheng@627: msgid "" dongsheng@627: "It's also possible to get Mercurial to run another program or script instead " dongsheng@627: "of <command>hgmerge</command>, by setting the <envar>HGMERGE</envar> " dongsheng@627: "environment variable to the name of your preferred program." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:210 dongsheng@627: msgid "Using a graphical merge tool" dongsheng@627: msgstr "使用图形合并工具" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:212 dongsheng@627: msgid "" dongsheng@627: "My preferred graphical merge tool is <command>kdiff3</command>, which I'll " dongsheng@627: "use to describe the features that are common to graphical file merging " dongsheng@627: "tools. You can see a screenshot of <command>kdiff3</command> in action in " dongsheng@627: "figure <xref linkend=\"fig.tour-merge.kdiff3\"/>. The kind of merge it is " dongsheng@627: "performing is called a <emphasis>three-way merge</emphasis>, because there " dongsheng@627: "are three different versions of the file of interest to us. The tool thus " dongsheng@627: "splits the upper portion of the window into three panes:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:222 dongsheng@627: msgid "" dongsheng@627: "At the left is the <emphasis>base</emphasis> version of the file, i.e. the " dongsheng@627: "most recent version from which the two versions we're trying to merge are " dongsheng@627: "descended." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:227 dongsheng@627: msgid "" dongsheng@627: "In the middle is <quote>our</quote> version of the file, with the contents " dongsheng@627: "that we modified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:230 dongsheng@627: msgid "" dongsheng@627: "On the right is <quote>their</quote> version of the file, the one that from " dongsheng@627: "the changeset that we're trying to merge with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:234 dongsheng@627: msgid "" dongsheng@627: "In the pane below these is the current <emphasis>result</emphasis> of the " dongsheng@627: "merge. Our task is to replace all of the red text, which indicates unresolved " dongsheng@627: "conflicts, with some sensible merger of the <quote>ours</quote> and " dongsheng@627: "<quote>theirs</quote> versions of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:241 dongsheng@627: msgid "" dongsheng@627: "All four of these panes are <emphasis>locked together</emphasis>; if we " dongsheng@627: "scroll vertically or horizontally in any of them, the others are updated to " dongsheng@627: "display the corresponding sections of their respective files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:247 dongsheng@630: msgid "" dongsheng@630: "<imageobject><imagedata width=\"100%\" fileref=\"images/kdiff3.png\"/></" dongsheng@630: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:250 dongsheng@627: msgid "Using <command>kdiff3</command> to merge versions of a file" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:255 dongsheng@627: msgid "" dongsheng@627: "For each conflicting portion of the file, we can choose to resolve the " dongsheng@627: "conflict using some combination of text from the base version, ours, or " dongsheng@627: "theirs. We can also manually edit the merged file at any time, in case we " dongsheng@627: "need to make further modifications." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:261 dongsheng@627: msgid "" dongsheng@627: "There are <emphasis>many</emphasis> file merging tools available, too many to " dongsheng@627: "cover here. They vary in which platforms they are available for, and in " dongsheng@627: "their particular strengths and weaknesses. Most are tuned for merging files " dongsheng@627: "containing plain text, while a few are aimed at specialised file formats " dongsheng@627: "(generally XML)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:270 dongsheng@627: msgid "A worked example" dongsheng@627: msgstr "合并实例" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:272 dongsheng@627: msgid "" dongsheng@627: "In this example, we will reproduce the file modification history of figure " dongsheng@627: "<xref linkend=\"fig.tour-merge.conflict\"/> above. Let's begin by creating a " dongsheng@627: "repository with a base version of our document." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:279 dongsheng@627: msgid "We'll clone the repository and make a change to the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:284 dongsheng@627: msgid "" dongsheng@627: "And another clone, to simulate someone else making a change to the file. " dongsheng@627: "(This hints at the idea that it's not all that unusual to merge with yourself " dongsheng@627: "when you isolate tasks in separate repositories, and indeed to find and " dongsheng@627: "resolve conflicts while doing so.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:292 dongsheng@627: msgid "" dongsheng@627: "Having created two different versions of the file, we'll set up an " dongsheng@627: "environment suitable for running our merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:298 dongsheng@627: msgid "" dongsheng@627: "In this example, I won't use Mercurial's normal <command>hgmerge</command> " dongsheng@627: "program to do the merge, because it would drop my nice automated example-" dongsheng@627: "running tool into a graphical user interface. Instead, I'll set " dongsheng@627: "<envar>HGMERGE</envar> to tell Mercurial to use the non-interactive " dongsheng@627: "<command>merge</command> command. This is bundled with many Unix-like " dongsheng@627: "systems. If you're following this example on your computer, don't bother " dongsheng@627: "setting <envar>HGMERGE</envar>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:308 dongsheng@627: msgid "<emphasis role=\"bold\">XXX FIX THIS EXAMPLE.</emphasis>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:313 dongsheng@627: msgid "" dongsheng@627: "Because <command>merge</command> can't resolve the conflicting changes, it " dongsheng@627: "leaves <emphasis>merge markers</emphasis> inside the file that has conflicts, " dongsheng@627: "indicating which lines have conflicts, and whether they came from our version " dongsheng@627: "of the file or theirs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:319 dongsheng@627: msgid "" dongsheng@627: "Mercurial can tell from the way <command>merge</command> exits that it wasn't " dongsheng@627: "able to merge successfully, so it tells us what commands we'll need to run if " dongsheng@627: "we want to redo the merging operation. This could be useful if, for example, " dongsheng@627: "we were running a graphical merge tool and quit because we were confused or " dongsheng@627: "realised we had made a mistake." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:326 dongsheng@627: msgid "" dongsheng@627: "If automatic or manual merges fail, there's nothing to prevent us from " dongsheng@627: "<quote>fixing up</quote> the affected files ourselves, and committing the " dongsheng@627: "results of our merge:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:335 dongsheng@627: msgid "Simplifying the pull-merge-commit sequence" dongsheng@627: msgstr "简化拉-合并-提交程序" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:337 dongsheng@627: msgid "" dongsheng@627: "The process of merging changes as outlined above is straightforward, but " dongsheng@627: "requires running three commands in sequence." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:343 dongsheng@627: msgid "" dongsheng@627: "In the case of the final commit, you also need to enter a commit message, " dongsheng@627: "which is almost always going to be a piece of uninteresting " dongsheng@627: "<quote>boilerplate</quote> text." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:347 dongsheng@627: msgid "" dongsheng@627: "It would be nice to reduce the number of steps needed, if this were " dongsheng@627: "possible. Indeed, Mercurial is distributed with an extension called <literal " dongsheng@627: "role=\"hg-ext\">fetch</literal> that does just this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:352 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides a flexible extension mechanism that lets people extend its " dongsheng@627: "functionality, while keeping the core of Mercurial small and easy to deal " dongsheng@627: "with. Some extensions add new commands that you can use from the command " dongsheng@627: "line, while others work <quote>behind the scenes,</quote> for example adding " dongsheng@627: "capabilities to the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:359 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">fetch</literal> extension adds a new command " dongsheng@627: "called, not surprisingly, <command role=\"hg-cmd\">hg fetch</command>. This " dongsheng@627: "extension acts as a combination of <command role=\"hg-cmd\">hg pull</" dongsheng@627: "command>, <command role=\"hg-cmd\">hg update</command> and <command role=\"hg-" dongsheng@627: "cmd\">hg merge</command>. It begins by pulling changes from another " dongsheng@627: "repository into the current repository. If it finds that the changes added a " dongsheng@627: "new head to the repository, it begins a merge, then commits the result of the " dongsheng@627: "merge with an automatically-generated commit message. If no new heads were " dongsheng@627: "added, it updates the working directory to the new tip changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:372 dongsheng@627: msgid "" dongsheng@627: "Enabling the <literal role=\"hg-ext\">fetch</literal> extension is easy. " dongsheng@627: "Edit your <filename role=\"special\">.hgrc</filename>, and either go to the " dongsheng@627: "<literal role=\"rc-extensions\">extensions</literal> section or create an " dongsheng@627: "<literal role=\"rc-extensions\">extensions</literal> section. Then add a line " dongsheng@627: "that simply reads <quote><literal>fetch </literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:382 dongsheng@627: msgid "" dongsheng@627: "(Normally, on the right-hand side of the <quote><literal>=</literal></quote> " dongsheng@627: "would appear the location of the extension, but since the <literal role=\"hg-" dongsheng@627: "ext\">fetch</literal> extension is in the standard distribution, Mercurial " dongsheng@627: "knows where to search for it.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch04-concepts.xml:5 dongsheng@627: msgid "Behind the scenes" dongsheng@627: msgstr "Mercurial 内幕" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch04-concepts.xml:7 dongsheng@627: msgid "" dongsheng@627: "Unlike many revision control systems, the concepts upon which Mercurial is " dongsheng@627: "built are simple enough that it's easy to understand how the software really " dongsheng@627: "works. Knowing this certainly isn't necessary, but I find it useful to have " dongsheng@627: "a <quote>mental model</quote> of what's going on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch04-concepts.xml:13 dongsheng@627: msgid "" dongsheng@627: "This understanding gives me confidence that Mercurial has been carefully " dongsheng@627: "designed to be both <emphasis>safe</emphasis> and <emphasis>efficient</" dongsheng@627: "emphasis>. And just as importantly, if it's easy for me to retain a good " dongsheng@627: "idea of what the software is doing when I perform a revision control task, " dongsheng@627: "I'm less likely to be surprised by its behaviour." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch04-concepts.xml:20 dongsheng@627: msgid "" dongsheng@627: "In this chapter, we'll initially cover the core concepts behind Mercurial's " dongsheng@627: "design, then continue to discuss some of the interesting details of its " dongsheng@627: "implementation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:25 dongsheng@627: msgid "Mercurial's historical record" dongsheng@627: msgstr "Mercurial 的历史记录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:28 dongsheng@627: msgid "Tracking the history of a single file" dongsheng@627: msgstr "跟踪单一文件的历史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:30 dongsheng@627: msgid "" dongsheng@627: "When Mercurial tracks modifications to a file, it stores the history of that " dongsheng@627: "file in a metadata object called a <emphasis>filelog</emphasis>. Each entry " dongsheng@627: "in the filelog contains enough information to reconstruct one revision of the " dongsheng@627: "file that is being tracked. Filelogs are stored as files in the <filename " dongsheng@627: "role=\"special\" class=\"directory\">.hg/store/data</filename> directory. A " dongsheng@627: "filelog contains two kinds of information: revision data, and an index to " dongsheng@627: "help Mercurial to find a revision efficiently." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:41 dongsheng@627: msgid "" dongsheng@627: "A file that is large, or has a lot of history, has its filelog stored in " dongsheng@627: "separate data (<quote><literal>.d</literal></quote> suffix) and index " dongsheng@627: "(<quote><literal>.i</literal></quote> suffix) files. For small files without " dongsheng@627: "much history, the revision data and index are combined in a single " dongsheng@627: "<quote><literal>.i</literal></quote> file. The correspondence between a file " dongsheng@627: "in the working directory and the filelog that tracks its history in the " dongsheng@627: "repository is illustrated in figure <xref linkend=\"fig.concepts.filelog\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:53 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/filelog.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:56 dongsheng@627: msgid "" dongsheng@627: "Relationships between files in working directory and filelogs in repository" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:63 dongsheng@627: msgid "Managing tracked files" dongsheng@627: msgstr "管理跟踪的文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:65 dongsheng@627: msgid "" dongsheng@627: "Mercurial uses a structure called a <emphasis>manifest</emphasis> to collect " dongsheng@627: "together information about the files that it tracks. Each entry in the " dongsheng@627: "manifest contains information about the files present in a single changeset. " dongsheng@627: "An entry records which files are present in the changeset, the revision of " dongsheng@627: "each file, and a few other pieces of file metadata." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:75 dongsheng@627: msgid "Recording changeset information" dongsheng@627: msgstr "记录修改集信息" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:77 dongsheng@627: msgid "" dongsheng@627: "The <emphasis>changelog</emphasis> contains information about each " dongsheng@627: "changeset. Each revision records who committed a change, the changeset " dongsheng@627: "comment, other pieces of changeset-related information, and the revision of " dongsheng@627: "the manifest to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:85 dongsheng@627: msgid "Relationships between revisions" dongsheng@627: msgstr "版本之间的关系" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:87 dongsheng@627: msgid "" dongsheng@627: "Within a changelog, a manifest, or a filelog, each revision stores a pointer " dongsheng@627: "to its immediate parent (or to its two parents, if it's a merge revision). " dongsheng@627: "As I mentioned above, there are also relationships between revisions " dongsheng@627: "<emphasis>across</emphasis> these structures, and they are hierarchical in " dongsheng@627: "nature." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:94 dongsheng@627: msgid "" dongsheng@627: "For every changeset in a repository, there is exactly one revision stored in " dongsheng@627: "the changelog. Each revision of the changelog contains a pointer to a single " dongsheng@627: "revision of the manifest. A revision of the manifest stores a pointer to a " dongsheng@627: "single revision of each filelog tracked when that changeset was created. " dongsheng@627: "These relationships are illustrated in figure <xref linkend=\"fig.concepts." dongsheng@627: "metadata\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:103 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/metadata.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:105 dongsheng@627: msgid "Metadata relationships" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:110 dongsheng@627: msgid "" dongsheng@627: "As the illustration shows, there is <emphasis>not</emphasis> a <quote>one to " dongsheng@627: "one</quote> relationship between revisions in the changelog, manifest, or " dongsheng@627: "filelog. If the manifest hasn't changed between two changesets, the changelog " dongsheng@627: "entries for those changesets will point to the same revision of the " dongsheng@627: "manifest. If a file that Mercurial tracks hasn't changed between two " dongsheng@627: "changesets, the entry for that file in the two revisions of the manifest will " dongsheng@627: "point to the same revision of its filelog." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:123 dongsheng@627: msgid "Safe, efficient storage" dongsheng@627: msgstr "安全，高效的存储" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:125 dongsheng@627: msgid "" dongsheng@627: "The underpinnings of changelogs, manifests, and filelogs are provided by a " dongsheng@627: "single structure called the <emphasis>revlog</emphasis>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:130 dongsheng@627: msgid "Efficient storage" dongsheng@627: msgstr "高效存储" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:132 dongsheng@627: msgid "" dongsheng@627: "The revlog provides efficient storage of revisions using a <emphasis>delta</" dongsheng@627: "emphasis> mechanism. Instead of storing a complete copy of a file for each " dongsheng@627: "revision, it stores the changes needed to transform an older revision into " dongsheng@627: "the new revision. For many kinds of file data, these deltas are typically a " dongsheng@627: "fraction of a percent of the size of a full copy of a file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:140 dongsheng@627: msgid "" dongsheng@627: "Some obsolete revision control systems can only work with deltas of text " dongsheng@627: "files. They must either store binary files as complete snapshots or encoded " dongsheng@627: "into a text representation, both of which are wasteful approaches. Mercurial " dongsheng@627: "can efficiently handle deltas of files with arbitrary binary contents; it " dongsheng@627: "doesn't need to treat text as special." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:149 dongsheng@627: msgid "Safe operation" dongsheng@627: msgstr "安全操作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:151 dongsheng@627: msgid "" dongsheng@627: "Mercurial only ever <emphasis>appends</emphasis> data to the end of a revlog " dongsheng@627: "file. It never modifies a section of a file after it has written it. This is " dongsheng@627: "both more robust and efficient than schemes that need to modify or rewrite " dongsheng@627: "data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:157 dongsheng@627: msgid "" dongsheng@627: "In addition, Mercurial treats every write as part of a <emphasis>transaction</" dongsheng@627: "emphasis> that can span a number of files. A transaction is " dongsheng@627: "<emphasis>atomic</emphasis>: either the entire transaction succeeds and its " dongsheng@627: "effects are all visible to readers in one go, or the whole thing is undone. " dongsheng@627: "This guarantee of atomicity means that if you're running two copies of " dongsheng@627: "Mercurial, where one is reading data and one is writing it, the reader will " dongsheng@627: "never see a partially written result that might confuse it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:167 dongsheng@627: msgid "" dongsheng@627: "The fact that Mercurial only appends to files makes it easier to provide this " dongsheng@627: "transactional guarantee. The easier it is to do stuff like this, the more " dongsheng@627: "confident you should be that it's done correctly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:174 dongsheng@627: msgid "Fast retrieval" dongsheng@627: msgstr "快速检索" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:176 dongsheng@627: msgid "" dongsheng@627: "Mercurial cleverly avoids a pitfall common to all earlier revision control " dongsheng@627: "systems: the problem of <emphasis>inefficient retrieval</emphasis>. Most " dongsheng@627: "revision control systems store the contents of a revision as an incremental " dongsheng@627: "series of modifications against a <quote>snapshot</quote>. To reconstruct a " dongsheng@627: "specific revision, you must first read the snapshot, and then every one of " dongsheng@627: "the revisions between the snapshot and your target revision. The more " dongsheng@627: "history that a file accumulates, the more revisions you must read, hence the " dongsheng@627: "longer it takes to reconstruct a particular revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:188 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/snapshot.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:190 dongsheng@627: msgid "Snapshot of a revlog, with incremental deltas" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:195 dongsheng@627: msgid "" dongsheng@627: "The innovation that Mercurial applies to this problem is simple but " dongsheng@627: "effective. Once the cumulative amount of delta information stored since the " dongsheng@627: "last snapshot exceeds a fixed threshold, it stores a new snapshot " dongsheng@627: "(compressed, of course), instead of another delta. This makes it possible to " dongsheng@627: "reconstruct <emphasis>any</emphasis> revision of a file quickly. This " dongsheng@627: "approach works so well that it has since been copied by several other " dongsheng@627: "revision control systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:204 dongsheng@627: msgid "" dongsheng@627: "Figure <xref linkend=\"fig.concepts.snapshot\"/> illustrates the idea. In an " dongsheng@627: "entry in a revlog's index file, Mercurial stores the range of entries from " dongsheng@627: "the data file that it must read to reconstruct a particular revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch04-concepts.xml:210 dongsheng@627: msgid "Aside: the influence of video compression" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:212 dongsheng@627: msgid "" dongsheng@627: "If you're familiar with video compression or have ever watched a TV feed " dongsheng@627: "through a digital cable or satellite service, you may know that most video " dongsheng@627: "compression schemes store each frame of video as a delta against its " dongsheng@627: "predecessor frame. In addition, these schemes use <quote>lossy</quote> " dongsheng@627: "compression techniques to increase the compression ratio, so visual errors " dongsheng@627: "accumulate over the course of a number of inter-frame deltas." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:221 dongsheng@627: msgid "" dongsheng@627: "Because it's possible for a video stream to <quote>drop out</quote> " dongsheng@627: "occasionally due to signal glitches, and to limit the accumulation of " dongsheng@627: "artefacts introduced by the lossy compression process, video encoders " dongsheng@627: "periodically insert a complete frame (called a <quote>key frame</quote>) into " dongsheng@627: "the video stream; the next delta is generated against that frame. This means " dongsheng@627: "that if the video signal gets interrupted, it will resume once the next key " dongsheng@627: "frame is received. Also, the accumulation of encoding errors restarts anew " dongsheng@627: "with each key frame." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:235 dongsheng@627: msgid "Identification and strong integrity" dongsheng@627: msgstr "鉴别和强完整性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:237 dongsheng@627: msgid "" dongsheng@627: "Along with delta or snapshot information, a revlog entry contains a " dongsheng@627: "cryptographic hash of the data that it represents. This makes it difficult " dongsheng@627: "to forge the contents of a revision, and easy to detect accidental corruption." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:242 dongsheng@627: msgid "" dongsheng@627: "Hashes provide more than a mere check against corruption; they are used as " dongsheng@627: "the identifiers for revisions. The changeset identification hashes that you " dongsheng@627: "see as an end user are from revisions of the changelog. Although filelogs " dongsheng@627: "and the manifest also use hashes, Mercurial only uses these behind the scenes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:249 dongsheng@627: msgid "" dongsheng@627: "Mercurial verifies that hashes are correct when it retrieves file revisions " dongsheng@627: "and when it pulls changes from another repository. If it encounters an " dongsheng@627: "integrity problem, it will complain and stop whatever it's doing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:254 dongsheng@627: msgid "" dongsheng@627: "In addition to the effect it has on retrieval efficiency, Mercurial's use of " dongsheng@627: "periodic snapshots makes it more robust against partial data corruption. If " dongsheng@627: "a revlog becomes partly corrupted due to a hardware error or system bug, it's " dongsheng@627: "often possible to reconstruct some or most revisions from the uncorrupted " dongsheng@627: "sections of the revlog, both before and after the corrupted section. This " dongsheng@627: "would not be possible with a delta-only storage model." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:266 dongsheng@627: msgid "Revision history, branching, and merging" dongsheng@627: msgstr "修订历史，分支与合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:268 dongsheng@627: msgid "" dongsheng@627: "Every entry in a Mercurial revlog knows the identity of its immediate " dongsheng@627: "ancestor revision, usually referred to as its <emphasis>parent</emphasis>. " dongsheng@627: "In fact, a revision contains room for not one parent, but two. Mercurial " dongsheng@627: "uses a special hash, called the <quote>null ID</quote>, to represent the idea " dongsheng@627: "<quote>there is no parent here</quote>. This hash is simply a string of " dongsheng@627: "zeroes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:276 dongsheng@627: msgid "" dongsheng@627: "In figure <xref linkend=\"fig.concepts.revlog\"/>, you can see an example of " dongsheng@627: "the conceptual structure of a revlog. Filelogs, manifests, and changelogs " dongsheng@627: "all have this same structure; they differ only in the kind of data stored in " dongsheng@627: "each delta or snapshot." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:282 dongsheng@627: msgid "" dongsheng@627: "The first revision in a revlog (at the bottom of the image) has the null ID " dongsheng@627: "in both of its parent slots. For a <quote>normal</quote> revision, its first " dongsheng@627: "parent slot contains the ID of its parent revision, and its second contains " dongsheng@627: "the null ID, indicating that the revision has only one real parent. Any two " dongsheng@627: "revisions that have the same parent ID are branches. A revision that " dongsheng@627: "represents a merge between branches has two normal revision IDs in its parent " dongsheng@627: "slots." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:292 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/revlog.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:299 dongsheng@627: msgid "The working directory" dongsheng@627: msgstr "工作目录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:301 dongsheng@627: msgid "" dongsheng@627: "In the working directory, Mercurial stores a snapshot of the files from the " dongsheng@627: "repository as of a particular changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:304 dongsheng@627: msgid "" dongsheng@627: "The working directory <quote>knows</quote> which changeset it contains. When " dongsheng@627: "you update the working directory to contain a particular changeset, Mercurial " dongsheng@627: "looks up the appropriate revision of the manifest to find out which files it " dongsheng@627: "was tracking at the time that changeset was committed, and which revision of " dongsheng@627: "each file was then current. It then recreates a copy of each of those files, " dongsheng@627: "with the same contents it had when the changeset was committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:313 dongsheng@627: msgid "" dongsheng@627: "The <emphasis>dirstate</emphasis> contains Mercurial's knowledge of the " dongsheng@627: "working directory. This details which changeset the working directory is " dongsheng@627: "updated to, and all of the files that Mercurial is tracking in the working " dongsheng@627: "directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:319 dongsheng@627: msgid "" dongsheng@627: "Just as a revision of a revlog has room for two parents, so that it can " dongsheng@627: "represent either a normal revision (with one parent) or a merge of two " dongsheng@627: "earlier revisions, the dirstate has slots for two parents. When you use the " dongsheng@627: "<command role=\"hg-cmd\">hg update</command> command, the changeset that you " dongsheng@627: "update to is stored in the <quote>first parent</quote> slot, and the null ID " dongsheng@627: "in the second. When you <command role=\"hg-cmd\">hg merge</command> with " dongsheng@627: "another changeset, the first parent remains unchanged, and the second parent " dongsheng@627: "is filled in with the changeset you're merging with. The <command role=\"hg-" dongsheng@627: "cmd\">hg parents</command> command tells you what the parents of the dirstate " dongsheng@627: "are." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:333 dongsheng@627: msgid "What happens when you commit" dongsheng@627: msgstr "当你提交时发生的事情" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:335 dongsheng@627: msgid "" dongsheng@627: "The dirstate stores parent information for more than just book-keeping " dongsheng@627: "purposes. Mercurial uses the parents of the dirstate as <emphasis>the " dongsheng@627: "parents of a new changeset</emphasis> when you perform a commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:341 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/wdir.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:343 dongsheng@627: msgid "The working directory can have two parents" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:348 dongsheng@627: msgid "" dongsheng@627: "Figure <xref linkend=\"fig.concepts.wdir\"/> shows the normal state of the " dongsheng@627: "working directory, where it has a single changeset as parent. That changeset " dongsheng@627: "is the <emphasis>tip</emphasis>, the newest changeset in the repository that " dongsheng@627: "has no children." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:355 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/wdir-after-commit.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:357 dongsheng@627: msgid "The working directory gains new parents after a commit" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:362 dongsheng@627: msgid "" dongsheng@627: "It's useful to think of the working directory as <quote>the changeset I'm " dongsheng@627: "about to commit</quote>. Any files that you tell Mercurial that you've " dongsheng@627: "added, removed, renamed, or copied will be reflected in that changeset, as " dongsheng@627: "will modifications to any files that Mercurial is already tracking; the new " dongsheng@627: "changeset will have the parents of the working directory as its parents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:370 dongsheng@627: msgid "" dongsheng@627: "After a commit, Mercurial will update the parents of the working directory, " dongsheng@627: "so that the first parent is the ID of the new changeset, and the second is " dongsheng@627: "the null ID. This is shown in figure <xref linkend=\"fig.concepts.wdir-after-" dongsheng@627: "commit\"/>. Mercurial doesn't touch any of the files in the working " dongsheng@627: "directory when you commit; it just modifies the dirstate to note its new " dongsheng@627: "parents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:381 dongsheng@627: msgid "Creating a new head" dongsheng@627: msgstr "创建新顶点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:383 dongsheng@627: msgid "" dongsheng@627: "It's perfectly normal to update the working directory to a changeset other " dongsheng@627: "than the current tip. For example, you might want to know what your project " dongsheng@627: "looked like last Tuesday, or you could be looking through changesets to see " dongsheng@627: "which one introduced a bug. In cases like this, the natural thing to do is " dongsheng@627: "update the working directory to the changeset you're interested in, and then " dongsheng@627: "examine the files in the working directory directly to see their contents as " dongsheng@627: "they were when you committed that changeset. The effect of this is shown in " dongsheng@627: "figure <xref linkend=\"fig.concepts.wdir-pre-branch\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:395 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/wdir-pre-branch.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:397 dongsheng@627: msgid "The working directory, updated to an older changeset" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:402 dongsheng@627: msgid "" dongsheng@627: "Having updated the working directory to an older changeset, what happens if " dongsheng@627: "you make some changes, and then commit? Mercurial behaves in the same way as " dongsheng@627: "I outlined above. The parents of the working directory become the parents of " dongsheng@627: "the new changeset. This new changeset has no children, so it becomes the new " dongsheng@627: "tip. And the repository now contains two changesets that have no children; " dongsheng@627: "we call these <emphasis>heads</emphasis>. You can see the structure that " dongsheng@627: "this creates in figure <xref linkend=\"fig.concepts.wdir-branch\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:414 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/wdir-branch.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:416 dongsheng@627: msgid "After a commit made while synced to an older changeset" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch04-concepts.xml:422 dongsheng@627: msgid "" dongsheng@627: "If you're new to Mercurial, you should keep in mind a common <quote>error</" dongsheng@627: "quote>, which is to use the <command role=\"hg-cmd\">hg pull</command> " dongsheng@627: "command without any options. By default, the <command role=\"hg-cmd\">hg " dongsheng@627: "pull</command> command <emphasis>does not</emphasis> update the working " dongsheng@627: "directory, so you'll bring new changesets into your repository, but the " dongsheng@627: "working directory will stay synced at the same changeset as before the pull. " dongsheng@627: "If you make some changes and commit afterwards, you'll thus create a new " dongsheng@627: "head, because your working directory isn't synced to whatever the current tip " dongsheng@627: "is." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch04-concepts.xml:434 dongsheng@627: msgid "" dongsheng@627: "I put the word <quote>error</quote> in quotes because all that you need to do " dongsheng@627: "to rectify this situation is <command role=\"hg-cmd\">hg merge</command>, " dongsheng@627: "then <command role=\"hg-cmd\">hg commit</command>. In other words, this " dongsheng@627: "almost never has negative consequences; it just surprises people. I'll " dongsheng@627: "discuss other ways to avoid this behaviour, and why Mercurial behaves in this " dongsheng@627: "initially surprising way, later on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:446 dongsheng@627: msgid "Merging heads" dongsheng@627: msgstr "合并顶点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:448 dongsheng@627: msgid "" dongsheng@627: "When you run the <command role=\"hg-cmd\">hg merge</command> command, " dongsheng@627: "Mercurial leaves the first parent of the working directory unchanged, and " dongsheng@627: "sets the second parent to the changeset you're merging with, as shown in " dongsheng@627: "figure <xref linkend=\"fig.concepts.wdir-merge\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:455 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/wdir-merge.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:457 dongsheng@627: msgid "Merging two heads" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:461 dongsheng@627: msgid "" dongsheng@627: "Mercurial also has to modify the working directory, to merge the files " dongsheng@627: "managed in the two changesets. Simplified a little, the merging process goes " dongsheng@627: "like this, for every file in the manifests of both changesets." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:466 dongsheng@627: msgid "If neither changeset has modified a file, do nothing with that file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:469 dongsheng@627: msgid "" dongsheng@627: "If one changeset has modified a file, and the other hasn't, create the " dongsheng@627: "modified copy of the file in the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:473 dongsheng@627: msgid "" dongsheng@627: "If one changeset has removed a file, and the other hasn't (or has also " dongsheng@627: "deleted it), delete the file from the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:477 dongsheng@627: msgid "" dongsheng@627: "If one changeset has removed a file, but the other has modified the file, ask " dongsheng@627: "the user what to do: keep the modified file, or remove it?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:481 dongsheng@627: msgid "" dongsheng@627: "If both changesets have modified a file, invoke an external merge program to " dongsheng@627: "choose the new contents for the merged file. This may require input from the " dongsheng@627: "user." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:486 dongsheng@627: msgid "" dongsheng@627: "If one changeset has modified a file, and the other has renamed or copied the " dongsheng@627: "file, make sure that the changes follow the new name of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:490 dongsheng@627: msgid "" dongsheng@627: "There are more details&emdash;merging has plenty of corner cases&emdash;but " dongsheng@627: "these are the most common choices that are involved in a merge. As you can " dongsheng@627: "see, most cases are completely automatic, and indeed most merges finish " dongsheng@627: "automatically, without requiring your input to resolve any conflicts." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:497 dongsheng@627: msgid "" dongsheng@627: "When you're thinking about what happens when you commit after a merge, once " dongsheng@627: "again the working directory is <quote>the changeset I'm about to commit</" dongsheng@627: "quote>. After the <command role=\"hg-cmd\">hg merge</command> command " dongsheng@627: "completes, the working directory has two parents; these will become the " dongsheng@627: "parents of the new changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:504 dongsheng@627: msgid "" dongsheng@627: "Mercurial lets you perform multiple merges, but you must commit the results " dongsheng@627: "of each individual merge as you go. This is necessary because Mercurial only " dongsheng@627: "tracks two parents for both revisions and the working directory. While it " dongsheng@627: "would be technically possible to merge multiple changesets at once, the " dongsheng@627: "prospect of user confusion and making a terrible mess of a merge immediately " dongsheng@627: "becomes overwhelming." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:515 dongsheng@627: msgid "Other interesting design features" dongsheng@627: msgstr "其它有趣的设计特性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:517 dongsheng@627: msgid "" dongsheng@627: "In the sections above, I've tried to highlight some of the most important " dongsheng@627: "aspects of Mercurial's design, to illustrate that it pays careful attention " dongsheng@627: "to reliability and performance. However, the attention to detail doesn't " dongsheng@627: "stop there. There are a number of other aspects of Mercurial's construction " dongsheng@627: "that I personally find interesting. I'll detail a few of them here, separate " dongsheng@627: "from the <quote>big ticket</quote> items above, so that if you're interested, " dongsheng@627: "you can gain a better idea of the amount of thinking that goes into a well-" dongsheng@627: "designed system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:528 dongsheng@627: msgid "Clever compression" dongsheng@627: msgstr "智能压缩" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:530 dongsheng@627: msgid "" dongsheng@627: "When appropriate, Mercurial will store both snapshots and deltas in " dongsheng@627: "compressed form. It does this by always <emphasis>trying to</emphasis> " dongsheng@627: "compress a snapshot or delta, but only storing the compressed version if it's " dongsheng@627: "smaller than the uncompressed version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:536 dongsheng@627: msgid "" dongsheng@627: "This means that Mercurial does <quote>the right thing</quote> when storing a " dongsheng@627: "file whose native form is compressed, such as a <literal>zip</literal> " dongsheng@627: "archive or a JPEG image. When these types of files are compressed a second " dongsheng@627: "time, the resulting file is usually bigger than the once-compressed form, and " dongsheng@627: "so Mercurial will store the plain <literal>zip</literal> or JPEG." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:544 dongsheng@627: msgid "" dongsheng@627: "Deltas between revisions of a compressed file are usually larger than " dongsheng@627: "snapshots of the file, and Mercurial again does <quote>the right thing</" dongsheng@627: "quote> in these cases. It finds that such a delta exceeds the threshold at " dongsheng@627: "which it should store a complete snapshot of the file, so it stores the " dongsheng@627: "snapshot, again saving space compared to a naive delta-only approach." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch04-concepts.xml:553 dongsheng@627: msgid "Network recompression" dongsheng@627: msgstr "网络重新压缩" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:555 dongsheng@627: msgid "" dongsheng@627: "When storing revisions on disk, Mercurial uses the <quote>deflate</quote> " dongsheng@627: "compression algorithm (the same one used by the popular <literal>zip</" dongsheng@627: "literal> archive format), which balances good speed with a respectable " dongsheng@627: "compression ratio. However, when transmitting revision data over a network " dongsheng@627: "connection, Mercurial uncompresses the compressed revision data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:563 dongsheng@627: msgid "" dongsheng@627: "If the connection is over HTTP, Mercurial recompresses the entire stream of " dongsheng@627: "data using a compression algorithm that gives a better compression ratio (the " dongsheng@627: "Burrows-Wheeler algorithm from the widely used <literal>bzip2</literal> " dongsheng@627: "compression package). This combination of algorithm and compression of the " dongsheng@627: "entire stream (instead of a revision at a time) substantially reduces the " dongsheng@627: "number of bytes to be transferred, yielding better network performance over " dongsheng@627: "almost all kinds of network." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:573 dongsheng@627: msgid "" dongsheng@627: "(If the connection is over <command>ssh</command>, Mercurial " dongsheng@627: "<emphasis>doesn't</emphasis> recompress the stream, because <command>ssh</" dongsheng@627: "command> can already do this itself.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:581 dongsheng@627: msgid "Read/write ordering and atomicity" dongsheng@627: msgstr "读写顺序与原子性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:583 dongsheng@627: msgid "" dongsheng@627: "Appending to files isn't the whole story when it comes to guaranteeing that a " dongsheng@627: "reader won't see a partial write. If you recall figure <xref linkend=\"fig." dongsheng@627: "concepts.metadata\"/>, revisions in the changelog point to revisions in the " dongsheng@627: "manifest, and revisions in the manifest point to revisions in filelogs. This " dongsheng@627: "hierarchy is deliberate." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:591 dongsheng@627: msgid "" dongsheng@627: "A writer starts a transaction by writing filelog and manifest data, and " dongsheng@627: "doesn't write any changelog data until those are finished. A reader starts " dongsheng@627: "by reading changelog data, then manifest data, followed by filelog data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:596 dongsheng@627: msgid "" dongsheng@627: "Since the writer has always finished writing filelog and manifest data before " dongsheng@627: "it writes to the changelog, a reader will never read a pointer to a partially " dongsheng@627: "written manifest revision from the changelog, and it will never read a " dongsheng@627: "pointer to a partially written filelog revision from the manifest." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:604 dongsheng@627: msgid "Concurrent access" dongsheng@627: msgstr "并发访问" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:606 dongsheng@627: msgid "" dongsheng@627: "The read/write ordering and atomicity guarantees mean that Mercurial never " dongsheng@627: "needs to <emphasis>lock</emphasis> a repository when it's reading data, even " dongsheng@627: "if the repository is being written to while the read is occurring. This has a " dongsheng@627: "big effect on scalability; you can have an arbitrary number of Mercurial " dongsheng@627: "processes safely reading data from a repository safely all at once, no matter " dongsheng@627: "whether it's being written to or not." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:615 dongsheng@627: msgid "" dongsheng@627: "The lockless nature of reading means that if you're sharing a repository on a " dongsheng@627: "multi-user system, you don't need to grant other local users permission to " dongsheng@627: "<emphasis>write</emphasis> to your repository in order for them to be able to " dongsheng@627: "clone it or pull changes from it; they only need <emphasis>read</emphasis> " dongsheng@627: "permission. (This is <emphasis>not</emphasis> a common feature among " dongsheng@627: "revision control systems, so don't take it for granted! Most require readers " dongsheng@627: "to be able to lock a repository to access it safely, and this requires write " dongsheng@627: "permission on at least one directory, which of course makes for all kinds of " dongsheng@627: "nasty and annoying security and administrative problems.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:628 dongsheng@627: msgid "" dongsheng@627: "Mercurial uses locks to ensure that only one process can write to a " dongsheng@627: "repository at a time (the locking mechanism is safe even over filesystems " dongsheng@627: "that are notoriously hostile to locking, such as NFS). If a repository is " dongsheng@627: "locked, a writer will wait for a while to retry if the repository becomes " dongsheng@627: "unlocked, but if the repository remains locked for too long, the process " dongsheng@627: "attempting to write will time out after a while. This means that your daily " dongsheng@627: "automated scripts won't get stuck forever and pile up if a system crashes " dongsheng@627: "unnoticed, for example. (Yes, the timeout is configurable, from zero to " dongsheng@627: "infinity.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch04-concepts.xml:640 dongsheng@627: msgid "Safe dirstate access" dongsheng@627: msgstr "安全的目录状态访问" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:642 dongsheng@627: msgid "" dongsheng@627: "As with revision data, Mercurial doesn't take a lock to read the dirstate " dongsheng@627: "file; it does acquire a lock to write it. To avoid the possibility of " dongsheng@627: "reading a partially written copy of the dirstate file, Mercurial writes to a " dongsheng@627: "file with a unique name in the same directory as the dirstate file, then " dongsheng@627: "renames the temporary file atomically to <filename>dirstate</filename>. The " dongsheng@627: "file named <filename>dirstate</filename> is thus guaranteed to be complete, " dongsheng@627: "not partially written." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:655 dongsheng@627: msgid "Avoiding seeks" dongsheng@627: msgstr "避免查找" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:657 dongsheng@627: msgid "" dongsheng@627: "Critical to Mercurial's performance is the avoidance of seeks of the disk " dongsheng@627: "head, since any seek is far more expensive than even a comparatively large " dongsheng@627: "read operation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:661 dongsheng@627: msgid "" dongsheng@627: "This is why, for example, the dirstate is stored in a single file. If there " dongsheng@627: "were a dirstate file per directory that Mercurial tracked, the disk would " dongsheng@627: "seek once per directory. Instead, Mercurial reads the entire single dirstate " dongsheng@627: "file in one step." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:667 dongsheng@627: msgid "" dongsheng@627: "Mercurial also uses a <quote>copy on write</quote> scheme when cloning a " dongsheng@627: "repository on local storage. Instead of copying every revlog file from the " dongsheng@627: "old repository into the new repository, it makes a <quote>hard link</quote>, " dongsheng@627: "which is a shorthand way to say <quote>these two names point to the same " dongsheng@627: "file</quote>. When Mercurial is about to write to one of a revlog's files, " dongsheng@627: "it checks to see if the number of names pointing at the file is greater than " dongsheng@627: "one. If it is, more than one repository is using the file, so Mercurial " dongsheng@627: "makes a new copy of the file that is private to this repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:678 dongsheng@627: msgid "" dongsheng@627: "A few revision control developers have pointed out that this idea of making a " dongsheng@627: "complete private copy of a file is not very efficient in its use of storage. " dongsheng@627: "While this is true, storage is cheap, and this method gives the highest " dongsheng@627: "performance while deferring most book-keeping to the operating system. An " dongsheng@627: "alternative scheme would most likely reduce performance and increase the " dongsheng@627: "complexity of the software, each of which is much more important to the " dongsheng@627: "<quote>feel</quote> of day-to-day use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:690 dongsheng@627: msgid "Other contents of the dirstate" dongsheng@627: msgstr "目录状态的其它内容" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:692 dongsheng@627: msgid "" dongsheng@627: "Because Mercurial doesn't force you to tell it when you're modifying a file, " dongsheng@627: "it uses the dirstate to store some extra information so it can determine " dongsheng@627: "efficiently whether you have modified a file. For each file in the working " dongsheng@627: "directory, it stores the time that it last modified the file itself, and the " dongsheng@627: "size of the file at that time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:699 dongsheng@627: msgid "" dongsheng@627: "When you explicitly <command role=\"hg-cmd\">hg add</command>, <command role=" dongsheng@627: "\"hg-cmd\">hg remove</command>, <command role=\"hg-cmd\">hg rename</command> " dongsheng@627: "or <command role=\"hg-cmd\">hg copy</command> files, Mercurial updates the " dongsheng@627: "dirstate so that it knows what to do with those files when you commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:706 dongsheng@627: msgid "" dongsheng@627: "When Mercurial is checking the states of files in the working directory, it " dongsheng@627: "first checks a file's modification time. If that has not changed, the file " dongsheng@627: "must not have been modified. If the file's size has changed, the file must " dongsheng@627: "have been modified. If the modification time has changed, but the size has " dongsheng@627: "not, only then does Mercurial need to read the actual contents of the file to " dongsheng@627: "see if they've changed. Storing these few extra pieces of information " dongsheng@627: "dramatically reduces the amount of data that Mercurial needs to read, which " dongsheng@627: "yields large performance improvements compared to other revision control " dongsheng@627: "systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch05-daily.xml:5 dongsheng@627: msgid "Mercurial in daily use" dongsheng@627: msgstr "Mercurial 的日常使用" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:8 dongsheng@627: msgid "Telling Mercurial which files to track" dongsheng@627: msgstr "告诉 Mercurial 要跟踪哪些文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:10 dongsheng@627: msgid "" dongsheng@627: "Mercurial does not work with files in your repository unless you tell it to " dongsheng@627: "manage them. The <command role=\"hg-cmd\">hg status</command> command will " dongsheng@627: "tell you which files Mercurial doesn't know about; it uses a <quote><literal>?" dongsheng@627: "</literal></quote> to display such files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:17 dongsheng@627: msgid "" dongsheng@627: "To tell Mercurial to track a file, use the <command role=\"hg-cmd\">hg add</" dongsheng@627: "command> command. Once you have added a file, the entry in the output of " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> for that file changes from " dongsheng@627: "<quote><literal>?</literal></quote> to <quote><literal>A</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:26 dongsheng@627: msgid "" dongsheng@627: "After you run a <command role=\"hg-cmd\">hg commit</command>, the files that " dongsheng@627: "you added before the commit will no longer be listed in the output of " dongsheng@627: "<command role=\"hg-cmd\">hg status</command>. The reason for this is that " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> only tells you about " dongsheng@627: "<quote>interesting</quote> files&emdash;those that you have modified or told " dongsheng@627: "Mercurial to do something with&emdash;by default. If you have a repository " dongsheng@627: "that contains thousands of files, you will rarely want to know about files " dongsheng@627: "that Mercurial is tracking, but that have not changed. (You can still get " dongsheng@627: "this information; we'll return to this later.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:38 dongsheng@627: msgid "" dongsheng@627: "Once you add a file, Mercurial doesn't do anything with it immediately. " dongsheng@627: "Instead, it will take a snapshot of the file's state the next time you " dongsheng@627: "perform a commit. It will then continue to track the changes you make to the " dongsheng@627: "file every time you commit, until you remove the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:45 dongsheng@627: msgid "Explicit versus implicit file naming" dongsheng@627: msgstr "明确与隐含文件命名" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:47 dongsheng@627: msgid "" dongsheng@627: "A useful behaviour that Mercurial has is that if you pass the name of a " dongsheng@627: "directory to a command, every Mercurial command will treat this as <quote>I " dongsheng@627: "want to operate on every file in this directory and its subdirectories</" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:54 dongsheng@627: msgid "" dongsheng@627: "Notice in this example that Mercurial printed the names of the files it " dongsheng@627: "added, whereas it didn't do so when we added the file named <filename>a</" dongsheng@627: "filename> in the earlier example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:59 dongsheng@627: msgid "" dongsheng@627: "What's going on is that in the former case, we explicitly named the file to " dongsheng@627: "add on the command line, so the assumption that Mercurial makes in such cases " dongsheng@627: "is that you know what you were doing, and it doesn't print any output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:64 dongsheng@627: msgid "" dongsheng@627: "However, when we <emphasis>imply</emphasis> the names of files by giving the " dongsheng@627: "name of a directory, Mercurial takes the extra step of printing the name of " dongsheng@627: "each file that it does something with. This makes it more clear what is " dongsheng@627: "happening, and reduces the likelihood of a silent and nasty surprise. This " dongsheng@627: "behaviour is common to most Mercurial commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:73 dongsheng@627: msgid "Aside: Mercurial tracks files, not directories" dongsheng@627: msgstr "旁白: Mercurial 只跟踪文件，不跟踪目录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:75 dongsheng@627: msgid "" dongsheng@627: "Mercurial does not track directory information. Instead, it tracks the path " dongsheng@627: "to a file. Before creating a file, it first creates any missing directory " dongsheng@627: "components of the path. After it deletes a file, it then deletes any empty " dongsheng@627: "directories that were in the deleted file's path. This sounds like a trivial " dongsheng@627: "distinction, but it has one minor practical consequence: it is not possible " dongsheng@627: "to represent a completely empty directory in Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:84 dongsheng@627: msgid "" dongsheng@627: "Empty directories are rarely useful, and there are unintrusive workarounds " dongsheng@627: "that you can use to achieve an appropriate effect. The developers of " dongsheng@627: "Mercurial thus felt that the complexity that would be required to manage " dongsheng@627: "empty directories was not worth the limited benefit this feature would bring." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:91 dongsheng@627: msgid "" dongsheng@627: "If you need an empty directory in your repository, there are a few ways to " dongsheng@627: "achieve this. One is to create a directory, then <command role=\"hg-cmd\">hg " dongsheng@627: "add</command> a <quote>hidden</quote> file to that directory. On Unix-like " dongsheng@627: "systems, any file name that begins with a period (<quote><literal>.</" dongsheng@627: "literal></quote>) is treated as hidden by most commands and GUI tools. This " dongsheng@627: "approach is illustrated below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:102 dongsheng@627: msgid "" dongsheng@627: "Another way to tackle a need for an empty directory is to simply create one " dongsheng@627: "in your automated build scripts before they will need it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:109 dongsheng@627: msgid "How to stop tracking a file" dongsheng@627: msgstr "如何停止跟踪文件" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:111 dongsheng@627: msgid "" dongsheng@627: "Once you decide that a file no longer belongs in your repository, use the " dongsheng@627: "<command role=\"hg-cmd\">hg remove</command> command; this deletes the file, " dongsheng@627: "and tells Mercurial to stop tracking it. A removed file is represented in " dongsheng@627: "the output of <command role=\"hg-cmd\">hg status</command> with a " dongsheng@627: "<quote><literal>R</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:120 dongsheng@627: msgid "" dongsheng@627: "After you <command role=\"hg-cmd\">hg remove</command> a file, Mercurial will " dongsheng@627: "no longer track changes to that file, even if you recreate a file with the " dongsheng@627: "same name in your working directory. If you do recreate a file with the same " dongsheng@627: "name and want Mercurial to track the new file, simply <command role=\"hg-cmd" dongsheng@627: "\">hg add</command> it. Mercurial will know that the newly added file is not " dongsheng@627: "related to the old file of the same name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:129 dongsheng@627: msgid "Removing a file does not affect its history" dongsheng@627: msgstr "删除文件不影响历史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:131 dongsheng@627: msgid "It is important to understand that removing a file has only two effects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch05-daily.xml:134 dongsheng@627: msgid "It removes the current version of the file from the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch05-daily.xml:137 dongsheng@627: msgid "" dongsheng@627: "It stops Mercurial from tracking changes to the file, from the time of the " dongsheng@627: "next commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:140 dongsheng@627: msgid "" dongsheng@627: "Removing a file <emphasis>does not</emphasis> in any way alter the " dongsheng@627: "<emphasis>history</emphasis> of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:143 dongsheng@627: msgid "" dongsheng@627: "If you update the working directory to a changeset in which a file that you " dongsheng@627: "have removed was still tracked, it will reappear in the working directory, " dongsheng@627: "with the contents it had when you committed that changeset. If you then " dongsheng@627: "update the working directory to a later changeset, in which the file had been " dongsheng@627: "removed, Mercurial will once again remove the file from the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:153 dongsheng@627: msgid "Missing files" dongsheng@627: msgstr "丢失的文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:155 dongsheng@627: msgid "" dongsheng@627: "Mercurial considers a file that you have deleted, but not used <command role=" dongsheng@627: "\"hg-cmd\">hg remove</command> to delete, to be <emphasis>missing</" dongsheng@627: "emphasis>. A missing file is represented with <quote><literal>!</literal></" dongsheng@627: "quote> in the output of <command role=\"hg-cmd\">hg status</command>. " dongsheng@627: "Mercurial commands will not generally do anything with missing files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:165 dongsheng@627: msgid "" dongsheng@627: "If your repository contains a file that <command role=\"hg-cmd\">hg status</" dongsheng@627: "command> reports as missing, and you want the file to stay gone, you can run " dongsheng@627: "<command role=\"hg-cmd\">hg remove <option role=\"hg-opt-remove\">--after</" dongsheng@627: "option></command> at any time later on, to tell Mercurial that you really did " dongsheng@627: "mean to remove the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:175 dongsheng@627: msgid "" dongsheng@627: "On the other hand, if you deleted the missing file by accident, give <command " dongsheng@627: "role=\"hg-cmd\">hg revert</command> the name of the file to recover. It will " dongsheng@627: "reappear, in unmodified form." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:184 dongsheng@627: msgid "Aside: why tell Mercurial explicitly to remove a file?" dongsheng@627: msgstr "旁白: 为什么要明确告诉 Mercurial 删除文件?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:187 dongsheng@627: msgid "" dongsheng@627: "You might wonder why Mercurial requires you to explicitly tell it that you " dongsheng@627: "are deleting a file. Early during the development of Mercurial, it let you " dongsheng@627: "delete a file however you pleased; Mercurial would notice the absence of the " dongsheng@627: "file automatically when you next ran a <command role=\"hg-cmd\">hg commit</" dongsheng@627: "command>, and stop tracking the file. In practice, this made it too easy to " dongsheng@627: "accidentally remove a file without noticing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:198 dongsheng@627: msgid "Useful shorthand&emdash;adding and removing files in one step" dongsheng@627: msgstr "有用的速记&emdash;一个步骤添加和删除文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:201 dongsheng@627: msgid "" dongsheng@627: "Mercurial offers a combination command, <command role=\"hg-cmd\">hg " dongsheng@627: "addremove</command>, that adds untracked files and marks missing files as " dongsheng@627: "removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:207 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg commit</command> command also provides a " dongsheng@627: "<option role=\"hg-opt-commit\">-A</option> option that performs this same add-" dongsheng@627: "and-remove, immediately followed by a commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:217 dongsheng@627: msgid "Copying files" dongsheng@627: msgstr "复制文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:219 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides a <command role=\"hg-cmd\">hg copy</command> command that " dongsheng@627: "lets you make a new copy of a file. When you copy a file using this command, " dongsheng@627: "Mercurial makes a record of the fact that the new file is a copy of the " dongsheng@627: "original file. It treats these copied files specially when you merge your " dongsheng@627: "work with someone else's." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:227 dongsheng@627: msgid "The results of copying during a merge" dongsheng@627: msgstr "合并期间的复制结果" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:229 dongsheng@627: msgid "" dongsheng@627: "What happens during a merge is that changes <quote>follow</quote> a copy. To " dongsheng@627: "best illustrate what this means, let's create an example. We'll start with " dongsheng@627: "the usual tiny repository that contains a single file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:236 dongsheng@627: msgid "" dongsheng@627: "We need to do some work in parallel, so that we'll have something to merge. " dongsheng@627: "So let's clone our repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:242 dongsheng@627: msgid "" dongsheng@627: "Back in our initial repository, let's use the <command role=\"hg-cmd\">hg " dongsheng@627: "copy</command> command to make a copy of the first file we created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:248 dongsheng@627: msgid "" dongsheng@627: "If we look at the output of the <command role=\"hg-cmd\">hg status</command> " dongsheng@627: "command afterwards, the copied file looks just like a normal added file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:254 dongsheng@627: msgid "" dongsheng@627: "But if we pass the <option role=\"hg-opt-status\">-C</option> option to " dongsheng@627: "<command role=\"hg-cmd\">hg status</command>, it prints another line of " dongsheng@627: "output: this is the file that our newly-added file was copied <emphasis>from</" dongsheng@627: "emphasis>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:262 dongsheng@627: msgid "" dongsheng@627: "Now, back in the repository we cloned, let's make a change in parallel. " dongsheng@627: "We'll add a line of content to the original file that we created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:268 dongsheng@627: msgid "" dongsheng@627: "Now we have a modified <filename>file</filename> in this repository. When we " dongsheng@627: "pull the changes from the first repository, and merge the two heads, " dongsheng@627: "Mercurial will propagate the changes that we made locally to <filename>file</" dongsheng@627: "filename> into its copy, <filename>new-file</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:278 dongsheng@627: msgid "Why should changes follow copies?" dongsheng@627: msgstr "为什么复制后需要后续修改?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:280 dongsheng@627: msgid "" dongsheng@627: "This behaviour, of changes to a file propagating out to copies of the file, " dongsheng@627: "might seem esoteric, but in most cases it's highly desirable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:284 dongsheng@627: msgid "" dongsheng@627: "First of all, remember that this propagation <emphasis>only</emphasis> " dongsheng@627: "happens when you merge. So if you <command role=\"hg-cmd\">hg copy</command> " dongsheng@627: "a file, and subsequently modify the original file during the normal course of " dongsheng@627: "your work, nothing will happen." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:290 dongsheng@627: msgid "" dongsheng@627: "The second thing to know is that modifications will only propagate across a " dongsheng@627: "copy as long as the repository that you're pulling changes from " dongsheng@627: "<emphasis>doesn't know</emphasis> about the copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:295 dongsheng@627: msgid "" dongsheng@627: "The reason that Mercurial does this is as follows. Let's say I make an " dongsheng@627: "important bug fix in a source file, and commit my changes. Meanwhile, you've " dongsheng@627: "decided to <command role=\"hg-cmd\">hg copy</command> the file in your " dongsheng@627: "repository, without knowing about the bug or having seen the fix, and you " dongsheng@627: "have started hacking on your copy of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:302 dongsheng@627: msgid "" dongsheng@627: "If you pulled and merged my changes, and Mercurial <emphasis>didn't</" dongsheng@627: "emphasis> propagate changes across copies, your source file would now contain " dongsheng@627: "the bug, and unless you remembered to propagate the bug fix by hand, the bug " dongsheng@627: "would <emphasis>remain</emphasis> in your copy of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:308 dongsheng@627: msgid "" dongsheng@627: "By automatically propagating the change that fixed the bug from the original " dongsheng@627: "file to the copy, Mercurial prevents this class of problem. To my knowledge, " dongsheng@627: "Mercurial is the <emphasis>only</emphasis> revision control system that " dongsheng@627: "propagates changes across copies like this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:314 dongsheng@627: msgid "" dongsheng@627: "Once your change history has a record that the copy and subsequent merge " dongsheng@627: "occurred, there's usually no further need to propagate changes from the " dongsheng@627: "original file to the copied file, and that's why Mercurial only propagates " dongsheng@627: "changes across copies until this point, and no further." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:322 dongsheng@627: msgid "How to make changes <emphasis>not</emphasis> follow a copy" dongsheng@627: msgstr "如何让复制后<emphasis>不</emphasis>修改?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:325 dongsheng@627: msgid "" dongsheng@627: "If, for some reason, you decide that this business of automatically " dongsheng@627: "propagating changes across copies is not for you, simply use your system's " dongsheng@627: "normal file copy command (on Unix-like systems, that's <command>cp</command>) " dongsheng@627: "to make a copy of a file, then <command role=\"hg-cmd\">hg add</command> the " dongsheng@627: "new copy by hand. Before you do so, though, please do reread section <xref " dongsheng@627: "linkend=\"sec.daily.why-copy\"/>, and make an informed decision that this " dongsheng@627: "behaviour is not appropriate to your specific case." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:338 dongsheng@627: msgid "Behaviour of the <command role=\"hg-cmd\">hg copy</command> command" dongsheng@627: msgstr "命令 <command role=\"hg-cmd\">hg copy</command> 的特性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:341 dongsheng@627: msgid "" dongsheng@627: "When you use the <command role=\"hg-cmd\">hg copy</command> command, " dongsheng@627: "Mercurial makes a copy of each source file as it currently stands in the " dongsheng@627: "working directory. This means that if you make some modifications to a file, " dongsheng@627: "then <command role=\"hg-cmd\">hg copy</command> it without first having " dongsheng@627: "committed those changes, the new copy will also contain the modifications you " dongsheng@627: "have made up until that point. (I find this behaviour a little " dongsheng@627: "counterintuitive, which is why I mention it here.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:351 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg copy</command> command acts similarly to the " dongsheng@627: "Unix <command>cp</command> command (you can use the <command role=\"hg-cmd" dongsheng@627: "\">hg cp</command> alias if you prefer). The last argument is the " dongsheng@627: "<emphasis>destination</emphasis>, and all prior arguments are " dongsheng@627: "<emphasis>sources</emphasis>. If you pass it a single file as the source, " dongsheng@627: "and the destination does not exist, it creates a new file with that name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:362 dongsheng@627: msgid "" dongsheng@627: "If the destination is a directory, Mercurial copies its sources into that " dongsheng@627: "directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:367 dongsheng@627: msgid "" dongsheng@627: "Copying a directory is recursive, and preserves the directory structure of " dongsheng@627: "the source." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:373 dongsheng@627: msgid "" dongsheng@627: "If the source and destination are both directories, the source tree is " dongsheng@627: "recreated in the destination directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:378 dongsheng@627: msgid "" dongsheng@627: "As with the <command role=\"hg-cmd\">hg rename</command> command, if you copy " dongsheng@627: "a file manually and then want Mercurial to know that you've copied the file, " dongsheng@627: "simply use the <option role=\"hg-opt-copy\">--after</option> option to " dongsheng@627: "<command role=\"hg-cmd\">hg copy</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:389 dongsheng@627: msgid "Renaming files" dongsheng@627: msgstr "改名文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:391 dongsheng@627: msgid "" dongsheng@627: "It's rather more common to need to rename a file than to make a copy of it. " dongsheng@627: "The reason I discussed the <command role=\"hg-cmd\">hg copy</command> command " dongsheng@627: "before talking about renaming files is that Mercurial treats a rename in " dongsheng@627: "essentially the same way as a copy. Therefore, knowing what Mercurial does " dongsheng@627: "when you copy a file tells you what to expect when you rename a file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:399 dongsheng@627: msgid "" dongsheng@627: "When you use the <command role=\"hg-cmd\">hg rename</command> command, " dongsheng@627: "Mercurial makes a copy of each source file, then deletes it and marks the " dongsheng@627: "file as removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:405 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg status</command> command shows the newly " dongsheng@627: "copied file as added, and the copied-from file as removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:411 dongsheng@627: msgid "" dongsheng@627: "As with the results of a <command role=\"hg-cmd\">hg copy</command>, we must " dongsheng@627: "use the <option role=\"hg-opt-status\">-C</option> option to <command role=" dongsheng@627: "\"hg-cmd\">hg status</command> to see that the added file is really being " dongsheng@627: "tracked by Mercurial as a copy of the original, now removed, file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:420 dongsheng@627: msgid "" dongsheng@627: "As with <command role=\"hg-cmd\">hg remove</command> and <command role=\"hg-" dongsheng@627: "cmd\">hg copy</command>, you can tell Mercurial about a rename after the fact " dongsheng@627: "using the <option role=\"hg-opt-rename\">--after</option> option. In most " dongsheng@627: "other respects, the behaviour of the <command role=\"hg-cmd\">hg rename</" dongsheng@627: "command> command, and the options it accepts, are similar to the <command " dongsheng@627: "role=\"hg-cmd\">hg copy</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:430 dongsheng@627: msgid "Renaming files and merging changes" dongsheng@627: msgstr "改名文件与合并修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:432 dongsheng@627: msgid "" dongsheng@627: "Since Mercurial's rename is implemented as copy-and-remove, the same " dongsheng@627: "propagation of changes happens when you merge after a rename as after a copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:436 dongsheng@627: msgid "" dongsheng@627: "If I modify a file, and you rename it to a new name, and then we merge our " dongsheng@627: "respective changes, my modifications to the file under its original name will " dongsheng@627: "be propagated into the file under its new name. (This is something you might " dongsheng@627: "expect to <quote>simply work,</quote> but not all revision control systems " dongsheng@627: "actually do this.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:443 dongsheng@627: msgid "" dongsheng@627: "Whereas having changes follow a copy is a feature where you can perhaps nod " dongsheng@627: "and say <quote>yes, that might be useful,</quote> it should be clear that " dongsheng@627: "having them follow a rename is definitely important. Without this facility, " dongsheng@627: "it would simply be too easy for changes to become orphaned when files are " dongsheng@627: "renamed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:452 dongsheng@627: msgid "Divergent renames and merging" dongsheng@627: msgstr "改名与合并的分歧" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:454 dongsheng@627: msgid "" dongsheng@627: "The case of diverging names occurs when two developers start with a " dongsheng@627: "file&emdash;let's call it <filename>foo</filename>&emdash;in their respective " dongsheng@627: "repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:461 dongsheng@627: msgid "Anne renames the file to <filename>bar</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:465 dongsheng@627: msgid "Meanwhile, Bob renames it to <filename>quux</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:470 dongsheng@627: msgid "" dongsheng@627: "I like to think of this as a conflict because each developer has expressed " dongsheng@627: "different intentions about what the file ought to be named." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:474 dongsheng@627: msgid "" dongsheng@627: "What do you think should happen when they merge their work? Mercurial's " dongsheng@627: "actual behaviour is that it always preserves <emphasis>both</emphasis> names " dongsheng@627: "when it merges changesets that contain divergent renames." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:481 dongsheng@627: msgid "" dongsheng@627: "Notice that Mercurial does warn about the divergent renames, but it leaves it " dongsheng@627: "up to you to do something about the divergence after the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:487 dongsheng@627: msgid "Convergent renames and merging" dongsheng@627: msgstr "收敛改名与合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:489 dongsheng@627: msgid "" dongsheng@627: "Another kind of rename conflict occurs when two people choose to rename " dongsheng@627: "different <emphasis>source</emphasis> files to the same " dongsheng@627: "<emphasis>destination</emphasis>. In this case, Mercurial runs its normal " dongsheng@627: "merge machinery, and lets you guide it to a suitable resolution." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:497 dongsheng@627: msgid "Other name-related corner cases" dongsheng@627: msgstr "其它名称相关的角落" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:499 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a longstanding bug in which it fails to handle a merge where " dongsheng@627: "one side has a file with a given name, while another has a directory with the " dongsheng@627: "same name. This is documented as <ulink role=\"hg-bug\" url=\"http://www." dongsheng@627: "selenic.com/mercurial/bts/issue29\">issue 29</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:511 dongsheng@627: msgid "Recovering from mistakes" dongsheng@627: msgstr "从错误恢复" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:513 dongsheng@627: msgid "" dongsheng@627: "Mercurial has some useful commands that will help you to recover from some " dongsheng@627: "common mistakes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:516 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg revert</command> command lets you undo " dongsheng@627: "changes that you have made to your working directory. For example, if you " dongsheng@627: "<command role=\"hg-cmd\">hg add</command> a file by accident, just run " dongsheng@627: "<command role=\"hg-cmd\">hg revert</command> with the name of the file you " dongsheng@627: "added, and while the file won't be touched in any way, it won't be tracked " dongsheng@627: "for adding by Mercurial any longer, either. You can also use <command role=" dongsheng@627: "\"hg-cmd\">hg revert</command> to get rid of erroneous changes to a file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:526 dongsheng@627: msgid "" dongsheng@627: "It's useful to remember that the <command role=\"hg-cmd\">hg revert</command> " dongsheng@627: "command is useful for changes that you have not yet committed. Once you've " dongsheng@627: "committed a change, if you decide it was a mistake, you can still do " dongsheng@627: "something about it, though your options may be more limited." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:532 dongsheng@627: msgid "" dongsheng@627: "For more information about the <command role=\"hg-cmd\">hg revert</command> " dongsheng@627: "command, and details about how to deal with changes you have already " dongsheng@627: "committed, see chapter <xref linkend=\"chap.undo\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch06-collab.xml:5 dongsheng@627: msgid "Collaborating with other people" dongsheng@627: msgstr "团体协作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch06-collab.xml:7 dongsheng@627: msgid "" dongsheng@627: "As a completely decentralised tool, Mercurial doesn't impose any policy on " dongsheng@627: "how people ought to work with each other. However, if you're new to " dongsheng@627: "distributed revision control, it helps to have some tools and examples in " dongsheng@627: "mind when you're thinking about possible workflow models." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:14 dongsheng@627: msgid "Mercurial's web interface" dongsheng@630: msgstr "Mercurial 的 web 接口" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:16 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a powerful web interface that provides several useful " dongsheng@627: "capabilities." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:19 dongsheng@627: msgid "" dongsheng@627: "For interactive use, the web interface lets you browse a single repository or " dongsheng@627: "a collection of repositories. You can view the history of a repository, " dongsheng@627: "examine each change (comments and diffs), and view the contents of each " dongsheng@627: "directory and file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:24 dongsheng@627: msgid "" dongsheng@627: "Also for human consumption, the web interface provides an RSS feed of the " dongsheng@627: "changes in a repository. This lets you <quote>subscribe</quote> to a " dongsheng@627: "repository using your favourite feed reader, and be automatically notified of " dongsheng@627: "activity in that repository as soon as it happens. I find this capability " dongsheng@627: "much more convenient than the model of subscribing to a mailing list to which " dongsheng@627: "notifications are sent, as it requires no additional configuration on the " dongsheng@627: "part of whoever is serving the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:34 dongsheng@627: msgid "" dongsheng@627: "The web interface also lets remote users clone a repository, pull changes " dongsheng@627: "from it, and (when the server is configured to permit it) push changes back " dongsheng@627: "to it. Mercurial's HTTP tunneling protocol aggressively compresses data, so " dongsheng@627: "that it works efficiently even over low-bandwidth network connections." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:40 dongsheng@627: msgid "" dongsheng@627: "The easiest way to get started with the web interface is to use your web " dongsheng@627: "browser to visit an existing repository, such as the master Mercurial " dongsheng@627: "repository at <ulink url=\"http://www.selenic.com/repo/hg?style=gitweb" dongsheng@627: "\">http://www.selenic.com/repo/hg?style=gitweb</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:45 dongsheng@627: msgid "" dongsheng@627: "If you're interested in providing a web interface to your own repositories, " dongsheng@627: "Mercurial provides two ways to do this. The first is using the <command role=" dongsheng@627: "\"hg-cmd\">hg serve</command> command, which is best suited to short-term " dongsheng@627: "<quote>lightweight</quote> serving. See section <xref linkend=\"sec.collab." dongsheng@627: "serve\"/> below for details of how to use this command. If you have a long-" dongsheng@627: "lived repository that you'd like to make permanently available, Mercurial has " dongsheng@627: "built-in support for the CGI (Common Gateway Interface) standard, which all " dongsheng@627: "common web servers support. See section <xref linkend=\"sec.collab.cgi\"/> " dongsheng@627: "for details of CGI configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:60 dongsheng@627: msgid "Collaboration models" dongsheng@630: msgstr "协作模型" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:62 dongsheng@627: msgid "" dongsheng@627: "With a suitably flexible tool, making decisions about workflow is much more " dongsheng@627: "of a social engineering challenge than a technical one. Mercurial imposes few " dongsheng@627: "limitations on how you can structure the flow of work in a project, so it's " dongsheng@627: "up to you and your group to set up and live with a model that matches your " dongsheng@627: "own particular needs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:70 dongsheng@627: msgid "Factors to keep in mind" dongsheng@630: msgstr "要牢记的因素" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:72 dongsheng@627: msgid "" dongsheng@627: "The most important aspect of any model that you must keep in mind is how well " dongsheng@627: "it matches the needs and capabilities of the people who will be using it. " dongsheng@627: "This might seem self-evident; even so, you still can't afford to forget it " dongsheng@627: "for a moment." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:78 dongsheng@627: msgid "" dongsheng@627: "I once put together a workflow model that seemed to make perfect sense to me, " dongsheng@627: "but that caused a considerable amount of consternation and strife within my " dongsheng@627: "development team. In spite of my attempts to explain why we needed a complex " dongsheng@627: "set of branches, and how changes ought to flow between them, a few team " dongsheng@627: "members revolted. Even though they were smart people, they didn't want to " dongsheng@627: "pay attention to the constraints we were operating under, or face the " dongsheng@627: "consequences of those constraints in the details of the model that I was " dongsheng@627: "advocating." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:88 dongsheng@627: msgid "" dongsheng@627: "Don't sweep foreseeable social or technical problems under the rug. Whatever " dongsheng@627: "scheme you put into effect, you should plan for mistakes and problem " dongsheng@627: "scenarios. Consider adding automated machinery to prevent, or quickly " dongsheng@627: "recover from, trouble that you can anticipate. As an example, if you intend " dongsheng@627: "to have a branch with not-for-release changes in it, you'd do well to think " dongsheng@627: "early about the possibility that someone might accidentally merge those " dongsheng@627: "changes into a release branch. You could avoid this particular problem by " dongsheng@627: "writing a hook that prevents changes from being merged from an inappropriate " dongsheng@627: "branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:102 dongsheng@627: msgid "Informal anarchy" dongsheng@630: msgstr "无政府状态" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:104 dongsheng@627: msgid "" dongsheng@627: "I wouldn't suggest an <quote>anything goes</quote> approach as something " dongsheng@627: "sustainable, but it's a model that's easy to grasp, and it works perfectly " dongsheng@627: "well in a few unusual situations." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:109 dongsheng@627: msgid "" dongsheng@627: "As one example, many projects have a loose-knit group of collaborators who " dongsheng@627: "rarely physically meet each other. Some groups like to overcome the " dongsheng@627: "isolation of working at a distance by organising occasional <quote>sprints</" dongsheng@627: "quote>. In a sprint, a number of people get together in a single location (a " dongsheng@627: "company's conference room, a hotel meeting room, that kind of place) and " dongsheng@627: "spend several days more or less locked in there, hacking intensely on a " dongsheng@627: "handful of projects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:118 dongsheng@627: msgid "" dongsheng@627: "A sprint is the perfect place to use the <command role=\"hg-cmd\">hg serve</" dongsheng@627: "command> command, since <command role=\"hg-cmd\">hg serve</command> does not " dongsheng@627: "require any fancy server infrastructure. You can get started with <command " dongsheng@627: "role=\"hg-cmd\">hg serve</command> in moments, by reading section <xref " dongsheng@627: "linkend=\"sec.collab.serve\"/> below. Then simply tell the person next to " dongsheng@627: "you that you're running a server, send the URL to them in an instant message, " dongsheng@627: "and you immediately have a quick-turnaround way to work together. They can " dongsheng@627: "type your URL into their web browser and quickly review your changes; or they " dongsheng@627: "can pull a bugfix from you and verify it; or they can clone a branch " dongsheng@627: "containing a new feature and try it out." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:132 dongsheng@627: msgid "" dongsheng@627: "The charm, and the problem, with doing things in an ad hoc fashion like this " dongsheng@627: "is that only people who know about your changes, and where they are, can see " dongsheng@627: "them. Such an informal approach simply doesn't scale beyond a handful " dongsheng@627: "people, because each individual needs to know about $n$ different " dongsheng@627: "repositories to pull from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:141 dongsheng@627: msgid "A single central repository" dongsheng@630: msgstr "单一中央版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:143 dongsheng@627: msgid "" dongsheng@627: "For smaller projects migrating from a centralised revision control tool, " dongsheng@627: "perhaps the easiest way to get started is to have changes flow through a " dongsheng@627: "single shared central repository. This is also the most common " dongsheng@627: "<quote>building block</quote> for more ambitious workflow schemes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:149 dongsheng@627: msgid "" dongsheng@627: "Contributors start by cloning a copy of this repository. They can pull " dongsheng@627: "changes from it whenever they need to, and some (perhaps all) developers have " dongsheng@627: "permission to push a change back when they're ready for other people to see " dongsheng@627: "it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:154 dongsheng@627: msgid "" dongsheng@627: "Under this model, it can still often make sense for people to pull changes " dongsheng@627: "directly from each other, without going through the central repository. " dongsheng@627: "Consider a case in which I have a tentative bug fix, but I am worried that if " dongsheng@627: "I were to publish it to the central repository, it might subsequently break " dongsheng@627: "everyone else's trees as they pull it. To reduce the potential for damage, I " dongsheng@627: "can ask you to clone my repository into a temporary repository of your own " dongsheng@627: "and test it. This lets us put off publishing the potentially unsafe change " dongsheng@627: "until it has had a little testing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:165 dongsheng@627: msgid "" dongsheng@627: "In this kind of scenario, people usually use the <command>ssh</command> " dongsheng@627: "protocol to securely push changes to the central repository, as documented in " dongsheng@627: "section <xref linkend=\"sec.collab.ssh\"/>. It's also usual to publish a " dongsheng@627: "read-only copy of the repository over HTTP using CGI, as in section <xref " dongsheng@627: "linkend=\"sec.collab.cgi\"/>. Publishing over HTTP satisfies the needs of " dongsheng@627: "people who don't have push access, and those who want to use web browsers to " dongsheng@627: "browse the repository's history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:178 dongsheng@627: msgid "Working with multiple branches" dongsheng@630: msgstr "使用多个分支工作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:180 dongsheng@627: msgid "" dongsheng@627: "Projects of any significant size naturally tend to make progress on several " dongsheng@627: "fronts simultaneously. In the case of software, it's common for a project to " dongsheng@627: "go through periodic official releases. A release might then go into " dongsheng@627: "<quote>maintenance mode</quote> for a while after its first publication; " dongsheng@627: "maintenance releases tend to contain only bug fixes, not new features. In " dongsheng@627: "parallel with these maintenance releases, one or more future releases may be " dongsheng@627: "under development. People normally use the word <quote>branch</quote> to " dongsheng@627: "refer to one of these many slightly different directions in which development " dongsheng@627: "is proceeding." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:193 dongsheng@627: msgid "" dongsheng@627: "Mercurial is particularly well suited to managing a number of simultaneous, " dongsheng@627: "but not identical, branches. Each <quote>development direction</quote> can " dongsheng@627: "live in its own central repository, and you can merge changes from one to " dongsheng@627: "another as the need arises. Because repositories are independent of each " dongsheng@627: "other, unstable changes in a development branch will never affect a stable " dongsheng@627: "branch unless someone explicitly merges those changes in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:202 dongsheng@627: msgid "" dongsheng@627: "Here's an example of how this can work in practice. Let's say you have one " dongsheng@627: "<quote>main branch</quote> on a central server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:208 dongsheng@627: msgid "People clone it, make changes locally, test them, and push them back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:211 dongsheng@627: msgid "" dongsheng@627: "Once the main branch reaches a release milestone, you can use the <command " dongsheng@627: "role=\"hg-cmd\">hg tag</command> command to give a permanent name to the " dongsheng@627: "milestone revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:217 dongsheng@627: msgid "Let's say some ongoing development occurs on the main branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:222 dongsheng@627: msgid "" dongsheng@627: "Using the tag that was recorded at the milestone, people who clone that " dongsheng@627: "repository at any time in the future can use <command role=\"hg-cmd\">hg " dongsheng@627: "update</command> to get a copy of the working directory exactly as it was " dongsheng@627: "when that tagged revision was committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:230 dongsheng@627: msgid "" dongsheng@627: "In addition, immediately after the main branch is tagged, someone can then " dongsheng@627: "clone the main branch on the server to a new <quote>stable</quote> branch, " dongsheng@627: "also on the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:236 dongsheng@627: msgid "" dongsheng@627: "Someone who needs to make a change to the stable branch can then clone " dongsheng@627: "<emphasis>that</emphasis> repository, make their changes, commit, and push " dongsheng@627: "their changes back there." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:242 dongsheng@627: msgid "" dongsheng@627: "Because Mercurial repositories are independent, and Mercurial doesn't move " dongsheng@627: "changes around automatically, the stable and main branches are " dongsheng@627: "<emphasis>isolated</emphasis> from each other. The changes that you made on " dongsheng@627: "the main branch don't <quote>leak</quote> to the stable branch, and vice " dongsheng@627: "versa." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:249 dongsheng@627: msgid "" dongsheng@627: "You'll often want all of your bugfixes on the stable branch to show up on the " dongsheng@627: "main branch, too. Rather than rewrite a bugfix on the main branch, you can " dongsheng@627: "simply pull and merge changes from the stable to the main branch, and " dongsheng@627: "Mercurial will bring those bugfixes in for you." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:257 dongsheng@627: msgid "" dongsheng@627: "The main branch will still contain changes that are not on the stable branch, " dongsheng@627: "but it will also contain all of the bugfixes from the stable branch. The " dongsheng@627: "stable branch remains unaffected by these changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch06-collab.xml:264 ../en/ch06-collab.xml:276 dongsheng@627: msgid "Feature branches" dongsheng@630: msgstr "特性分支" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:266 dongsheng@627: msgid "" dongsheng@627: "For larger projects, an effective way to manage change is to break up a team " dongsheng@627: "into smaller groups. Each group has a shared branch of its own, cloned from " dongsheng@627: "a single <quote>master</quote> branch used by the entire project. People " dongsheng@627: "working on an individual branch are typically quite isolated from " dongsheng@627: "developments on other branches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch06-collab.xml:274 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/feature-branches.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:280 dongsheng@627: msgid "" dongsheng@627: "When a particular feature is deemed to be in suitable shape, someone on that " dongsheng@627: "feature team pulls and merges from the master branch into the feature branch, " dongsheng@627: "then pushes back up to the master branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:287 dongsheng@627: msgid "The release train" dongsheng@630: msgstr "发布列车" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:289 dongsheng@627: msgid "" dongsheng@627: "Some projects are organised on a <quote>train</quote> basis: a release is " dongsheng@627: "scheduled to happen every few months, and whatever features are ready when " dongsheng@627: "the <quote>train</quote> is ready to leave are allowed in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:294 dongsheng@627: msgid "" dongsheng@627: "This model resembles working with feature branches. The difference is that " dongsheng@627: "when a feature branch misses a train, someone on the feature team pulls and " dongsheng@627: "merges the changes that went out on that train release into the feature " dongsheng@627: "branch, and the team continues its work on top of that release so that their " dongsheng@627: "feature can make the next release." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:303 dongsheng@627: msgid "The Linux kernel model" dongsheng@630: msgstr "Linux 内核模型" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:305 dongsheng@627: msgid "" dongsheng@627: "The development of the Linux kernel has a shallow hierarchical structure, " dongsheng@627: "surrounded by a cloud of apparent chaos. Because most Linux developers use " dongsheng@627: "<command>git</command>, a distributed revision control tool with capabilities " dongsheng@627: "similar to Mercurial, it's useful to describe the way work flows in that " dongsheng@627: "environment; if you like the ideas, the approach translates well across tools." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:313 dongsheng@627: msgid "" dongsheng@627: "At the center of the community sits Linus Torvalds, the creator of Linux. He " dongsheng@627: "publishes a single source repository that is considered the " dongsheng@627: "<quote>authoritative</quote> current tree by the entire developer community. " dongsheng@627: "Anyone can clone Linus's tree, but he is very choosy about whose trees he " dongsheng@627: "pulls from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:320 dongsheng@627: msgid "" dongsheng@627: "Linus has a number of <quote>trusted lieutenants</quote>. As a general rule, " dongsheng@627: "he pulls whatever changes they publish, in most cases without even reviewing " dongsheng@627: "those changes. Some of those lieutenants are generally agreed to be " dongsheng@627: "<quote>maintainers</quote>, responsible for specific subsystems within the " dongsheng@627: "kernel. If a random kernel hacker wants to make a change to a subsystem that " dongsheng@627: "they want to end up in Linus's tree, they must find out who the subsystem's " dongsheng@627: "maintainer is, and ask that maintainer to take their change. If the " dongsheng@627: "maintainer reviews their changes and agrees to take them, they'll pass them " dongsheng@627: "along to Linus in due course." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:332 dongsheng@627: msgid "" dongsheng@627: "Individual lieutenants have their own approaches to reviewing, accepting, and " dongsheng@627: "publishing changes; and for deciding when to feed them to Linus. In " dongsheng@627: "addition, there are several well known branches that people use for different " dongsheng@627: "purposes. For example, a few people maintain <quote>stable</quote> " dongsheng@627: "repositories of older versions of the kernel, to which they apply critical " dongsheng@627: "fixes as needed. Some maintainers publish multiple trees: one for " dongsheng@627: "experimental changes; one for changes that they are about to feed upstream; " dongsheng@627: "and so on. Others just publish a single tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:343 dongsheng@627: msgid "" dongsheng@627: "This model has two notable features. The first is that it's <quote>pull " dongsheng@627: "only</quote>. You have to ask, convince, or beg another developer to take a " dongsheng@627: "change from you, because there are almost no trees to which more than one " dongsheng@627: "person can push, and there's no way to push changes into a tree that someone " dongsheng@627: "else controls." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:350 dongsheng@627: msgid "" dongsheng@627: "The second is that it's based on reputation and acclaim. If you're an " dongsheng@627: "unknown, Linus will probably ignore changes from you without even " dongsheng@627: "responding. But a subsystem maintainer will probably review them, and will " dongsheng@627: "likely take them if they pass their criteria for suitability. The more " dongsheng@627: "<quote>good</quote> changes you contribute to a maintainer, the more likely " dongsheng@627: "they are to trust your judgment and accept your changes. If you're well-" dongsheng@627: "known and maintain a long-lived branch for something Linus hasn't yet " dongsheng@627: "accepted, people with similar interests may pull your changes regularly to " dongsheng@627: "keep up with your work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:361 dongsheng@627: msgid "" dongsheng@627: "Reputation and acclaim don't necessarily cross subsystem or <quote>people</" dongsheng@627: "quote> boundaries. If you're a respected but specialised storage hacker, and " dongsheng@627: "you try to fix a networking bug, that change will receive a level of scrutiny " dongsheng@627: "from a network maintainer comparable to a change from a complete stranger." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:368 dongsheng@627: msgid "" dongsheng@627: "To people who come from more orderly project backgrounds, the comparatively " dongsheng@627: "chaotic Linux kernel development process often seems completely insane. It's " dongsheng@627: "subject to the whims of individuals; people make sweeping changes whenever " dongsheng@627: "they deem it appropriate; and the pace of development is astounding. And yet " dongsheng@627: "Linux is a highly successful, well-regarded piece of software." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:378 dongsheng@627: msgid "Pull-only versus shared-push collaboration" dongsheng@630: msgstr "只读与共享写协作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:380 dongsheng@627: msgid "" dongsheng@627: "A perpetual source of heat in the open source community is whether a " dongsheng@627: "development model in which people only ever pull changes from others is " dongsheng@627: "<quote>better than</quote> one in which multiple people can push changes to a " dongsheng@627: "shared repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:386 dongsheng@627: msgid "" dongsheng@627: "Typically, the backers of the shared-push model use tools that actively " dongsheng@627: "enforce this approach. If you're using a centralised revision control tool " dongsheng@627: "such as Subversion, there's no way to make a choice over which model you'll " dongsheng@627: "use: the tool gives you shared-push, and if you want to do anything else, " dongsheng@627: "you'll have to roll your own approach on top (such as applying a patch by " dongsheng@627: "hand)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:394 dongsheng@627: msgid "" dongsheng@627: "A good distributed revision control tool, such as Mercurial, will support " dongsheng@627: "both models. You and your collaborators can then structure how you work " dongsheng@627: "together based on your own needs and preferences, not on what contortions " dongsheng@627: "your tools force you into." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:402 dongsheng@627: msgid "Where collaboration meets branch management" dongsheng@630: msgstr "协作与分支管理" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:404 dongsheng@627: msgid "" dongsheng@627: "Once you and your team set up some shared repositories and start propagating " dongsheng@627: "changes back and forth between local and shared repos, you begin to face a " dongsheng@627: "related, but slightly different challenge: that of managing the multiple " dongsheng@627: "directions in which your team may be moving at once. Even though this " dongsheng@627: "subject is intimately related to how your team collaborates, it's dense " dongsheng@627: "enough to merit treatment of its own, in chapter <xref linkend=\"chap.branch" dongsheng@627: "\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:416 dongsheng@627: msgid "The technical side of sharing" dongsheng@630: msgstr "共享的技术因素" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:418 dongsheng@627: msgid "" dongsheng@627: "The remainder of this chapter is devoted to the question of serving data to " dongsheng@627: "your collaborators." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:423 dongsheng@627: msgid "Informal sharing with <command role=\"hg-cmd\">hg serve</command>" dongsheng@630: msgstr "使用 <command role=\"hg-cmd\">hg serve</command> 进行非正式共享" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:426 dongsheng@627: msgid "" dongsheng@627: "Mercurial's <command role=\"hg-cmd\">hg serve</command> command is " dongsheng@627: "wonderfully suited to small, tight-knit, and fast-paced group environments. " dongsheng@627: "It also provides a great way to get a feel for using Mercurial commands over " dongsheng@627: "a network." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:431 dongsheng@627: msgid "" dongsheng@627: "Run <command role=\"hg-cmd\">hg serve</command> inside a repository, and in " dongsheng@627: "under a second it will bring up a specialised HTTP server; this will accept " dongsheng@627: "connections from any client, and serve up data for that repository until you " dongsheng@627: "terminate it. Anyone who knows the URL of the server you just started, and " dongsheng@627: "can talk to your computer over the network, can then use a web browser or " dongsheng@627: "Mercurial to read data from that repository. A URL for a <command role=\"hg-" dongsheng@627: "cmd\">hg serve</command> instance running on a laptop is likely to look " dongsheng@627: "something like <literal>http://my-laptop.local:8000/</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:442 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg serve</command> command is <emphasis>not</" dongsheng@627: "emphasis> a general-purpose web server. It can do only two things:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:446 dongsheng@627: msgid "" dongsheng@627: "Allow people to browse the history of the repository it's serving, from their " dongsheng@627: "normal web browsers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:450 dongsheng@627: msgid "" dongsheng@627: "Speak Mercurial's wire protocol, so that people can <command role=\"hg-cmd" dongsheng@627: "\">hg clone</command> or <command role=\"hg-cmd\">hg pull</command> changes " dongsheng@627: "from that repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:455 dongsheng@627: msgid "" dongsheng@627: "In particular, <command role=\"hg-cmd\">hg serve</command> won't allow remote " dongsheng@627: "users to <emphasis>modify</emphasis> your repository. It's intended for read-" dongsheng@627: "only use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:459 dongsheng@627: msgid "" dongsheng@627: "If you're getting started with Mercurial, there's nothing to prevent you from " dongsheng@627: "using <command role=\"hg-cmd\">hg serve</command> to serve up a repository on " dongsheng@627: "your own computer, then use commands like <command role=\"hg-cmd\">hg clone</" dongsheng@627: "command>, <command role=\"hg-cmd\">hg incoming</command>, and so on to talk " dongsheng@627: "to that server as if the repository was hosted remotely. This can help you to " dongsheng@627: "quickly get acquainted with using commands on network-hosted repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:469 dongsheng@627: msgid "A few things to keep in mind" dongsheng@630: msgstr "要牢记的几件事" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:471 dongsheng@627: msgid "" dongsheng@627: "Because it provides unauthenticated read access to all clients, you should " dongsheng@627: "only use <command role=\"hg-cmd\">hg serve</command> in an environment where " dongsheng@627: "you either don't care, or have complete control over, who can access your " dongsheng@627: "network and pull data from your repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:477 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg serve</command> command knows nothing about " dongsheng@627: "any firewall software you might have installed on your system or network. It " dongsheng@627: "cannot detect or control your firewall software. If other people are unable " dongsheng@627: "to talk to a running <command role=\"hg-cmd\">hg serve</command> instance, " dongsheng@627: "the second thing you should do (<emphasis>after</emphasis> you make sure that " dongsheng@627: "they're using the correct URL) is check your firewall configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:486 dongsheng@627: msgid "" dongsheng@627: "By default, <command role=\"hg-cmd\">hg serve</command> listens for incoming " dongsheng@627: "connections on port 8000. If another process is already listening on the " dongsheng@627: "port you want to use, you can specify a different port to listen on using the " dongsheng@627: "<option role=\"hg-opt-serve\">-p</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:492 dongsheng@627: msgid "" dongsheng@627: "Normally, when <command role=\"hg-cmd\">hg serve</command> starts, it prints " dongsheng@627: "no output, which can be a bit unnerving. If you'd like to confirm that it is " dongsheng@627: "indeed running correctly, and find out what URL you should send to your " dongsheng@627: "collaborators, start it with the <option role=\"hg-opt-global\">-v</option> " dongsheng@627: "option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:502 dongsheng@627: msgid "Using the Secure Shell (ssh) protocol" dongsheng@630: msgstr "使用 ssh 协议" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:504 dongsheng@627: msgid "" dongsheng@627: "You can pull and push changes securely over a network connection using the " dongsheng@627: "Secure Shell (<literal>ssh</literal>) protocol. To use this successfully, " dongsheng@627: "you may have to do a little bit of configuration on the client or server " dongsheng@627: "sides." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:509 dongsheng@627: msgid "" dongsheng@627: "If you're not familiar with ssh, it's a network protocol that lets you " dongsheng@627: "securely communicate with another computer. To use it with Mercurial, you'll " dongsheng@627: "be setting up one or more user accounts on a server so that remote users can " dongsheng@627: "log in and execute commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:515 dongsheng@627: msgid "" dongsheng@627: "(If you <emphasis>are</emphasis> familiar with ssh, you'll probably find some " dongsheng@627: "of the material that follows to be elementary in nature.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:520 dongsheng@627: msgid "How to read and write ssh URLs" dongsheng@630: msgstr "如何读写 ssh 路径" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:522 dongsheng@627: msgid "An ssh URL tends to look like this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:525 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>ssh://</literal></quote> part tells Mercurial to use the " dongsheng@627: "ssh protocol." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:528 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>bos@</literal></quote> component indicates what username " dongsheng@627: "to log into the server as. You can leave this out if the remote username is " dongsheng@627: "the same as your local username." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:533 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>hg.serpentine.com</literal></quote> gives the hostname of " dongsheng@627: "the server to log into." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:537 dongsheng@627: msgid "" dongsheng@627: "The <quote>:22</quote> identifies the port number to connect to the server " dongsheng@627: "on. The default port is 22, so you only need to specify this part if you're " dongsheng@627: "<emphasis>not</emphasis> using port 22." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:542 dongsheng@627: msgid "" dongsheng@627: "The remainder of the URL is the local path to the repository on the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:546 dongsheng@627: msgid "" dongsheng@627: "There's plenty of scope for confusion with the path component of ssh URLs, as " dongsheng@627: "there is no standard way for tools to interpret it. Some programs behave " dongsheng@627: "differently than others when dealing with these paths. This isn't an ideal " dongsheng@627: "situation, but it's unlikely to change. Please read the following paragraphs " dongsheng@627: "carefully." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:553 dongsheng@627: msgid "" dongsheng@627: "Mercurial treats the path to a repository on the server as relative to the " dongsheng@627: "remote user's home directory. For example, if user <literal>foo</literal> on " dongsheng@627: "the server has a home directory of <filename class=\"directory\">/home/foo</" dongsheng@627: "filename>, then an ssh URL that contains a path component of <filename class=" dongsheng@627: "\"directory\">bar</filename> <emphasis>really</emphasis> refers to the " dongsheng@627: "directory <filename class=\"directory\">/home/foo/bar</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:562 dongsheng@627: msgid "" dongsheng@627: "If you want to specify a path relative to another user's home directory, you " dongsheng@627: "can use a path that starts with a tilde character followed by the user's name " dongsheng@627: "(let's call them <literal>otheruser</literal>), like this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:568 dongsheng@627: msgid "" dongsheng@627: "And if you really want to specify an <emphasis>absolute</emphasis> path on " dongsheng@627: "the server, begin the path component with two slashes, as in this example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:575 dongsheng@627: msgid "Finding an ssh client for your system" dongsheng@630: msgstr "为你的系统寻找 ssh 客户端" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:577 dongsheng@627: msgid "" dongsheng@627: "Almost every Unix-like system comes with OpenSSH preinstalled. If you're " dongsheng@627: "using such a system, run <literal>which ssh</literal> to find out if the " dongsheng@627: "<command>ssh</command> command is installed (it's usually in <filename class=" dongsheng@627: "\"directory\">/usr/bin</filename>). In the unlikely event that it isn't " dongsheng@627: "present, take a look at your system documentation to figure out how to " dongsheng@627: "install it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:585 dongsheng@627: msgid "" dongsheng@627: "On Windows, you'll first need to download a suitable ssh client. There are " dongsheng@627: "two alternatives." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:588 dongsheng@627: msgid "" dongsheng@627: "Simon Tatham's excellent PuTTY package <citation>web:putty</citation> " dongsheng@627: "provides a complete suite of ssh client commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:592 dongsheng@627: msgid "" dongsheng@627: "If you have a high tolerance for pain, you can use the Cygwin port of OpenSSH." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:595 dongsheng@627: msgid "" dongsheng@627: "In either case, you'll need to edit your \\hgini\\ file to tell Mercurial " dongsheng@627: "where to find the actual client command. For example, if you're using PuTTY, " dongsheng@627: "you'll need to use the <command>plink</command> command as a command-line ssh " dongsheng@627: "client." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch06-collab.xml:604 dongsheng@627: msgid "" dongsheng@627: "The path to <command>plink</command> shouldn't contain any whitespace " dongsheng@627: "characters, or Mercurial may not be able to run it correctly (so putting it " dongsheng@627: "in <filename class=\"directory\">C:\\\\Program Files</filename> is probably " dongsheng@627: "not a good idea)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:613 dongsheng@627: msgid "Generating a key pair" dongsheng@630: msgstr "产生密钥对" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:615 dongsheng@627: msgid "" dongsheng@627: "To avoid the need to repetitively type a password every time you need to use " dongsheng@627: "your ssh client, I recommend generating a key pair. On a Unix-like system, " dongsheng@627: "the <command>ssh-keygen</command> command will do the trick. On Windows, if " dongsheng@627: "you're using PuTTY, the <command>puttygen</command> command is what you'll " dongsheng@627: "need." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:623 dongsheng@627: msgid "" dongsheng@627: "When you generate a key pair, it's usually <emphasis>highly</emphasis> " dongsheng@627: "advisable to protect it with a passphrase. (The only time that you might not " dongsheng@627: "want to do this is when you're using the ssh protocol for automated tasks on " dongsheng@627: "a secure network.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:629 dongsheng@627: msgid "" dongsheng@627: "Simply generating a key pair isn't enough, however. You'll need to add the " dongsheng@627: "public key to the set of authorised keys for whatever user you're logging in " dongsheng@627: "remotely as. For servers using OpenSSH (the vast majority), this will mean " dongsheng@627: "adding the public key to a list in a file called <filename role=\"special" dongsheng@627: "\">authorized_keys</filename> in their <filename role=\"special\" class=" dongsheng@627: "\"directory\">.ssh</filename> directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:638 dongsheng@627: msgid "" dongsheng@627: "On a Unix-like system, your public key will have a <filename>.pub</filename> " dongsheng@627: "extension. If you're using <command>puttygen</command> on Windows, you can " dongsheng@627: "save the public key to a file of your choosing, or paste it from the window " dongsheng@627: "it's displayed in straight into the <filename role=\"special" dongsheng@627: "\">authorized_keys</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:647 dongsheng@627: msgid "Using an authentication agent" dongsheng@630: msgstr "使用认证代理" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:649 dongsheng@627: msgid "" dongsheng@627: "An authentication agent is a daemon that stores passphrases in memory (so it " dongsheng@627: "will forget passphrases if you log out and log back in again). An ssh client " dongsheng@627: "will notice if it's running, and query it for a passphrase. If there's no " dongsheng@627: "authentication agent running, or the agent doesn't store the necessary " dongsheng@627: "passphrase, you'll have to type your passphrase every time Mercurial tries to " dongsheng@627: "communicate with a server on your behalf (e.g. whenever you pull or push " dongsheng@627: "changes)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:658 dongsheng@627: msgid "" dongsheng@627: "The downside of storing passphrases in an agent is that it's possible for a " dongsheng@627: "well-prepared attacker to recover the plain text of your passphrases, in some " dongsheng@627: "cases even if your system has been power-cycled. You should make your own " dongsheng@627: "judgment as to whether this is an acceptable risk. It certainly saves a lot " dongsheng@627: "of repeated typing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:665 dongsheng@627: msgid "" dongsheng@627: "On Unix-like systems, the agent is called <command>ssh-agent</command>, and " dongsheng@627: "it's often run automatically for you when you log in. You'll need to use the " dongsheng@627: "<command>ssh-add</command> command to add passphrases to the agent's store. " dongsheng@627: "On Windows, if you're using PuTTY, the <command>pageant</command> command " dongsheng@627: "acts as the agent. It adds an icon to your system tray that will let you " dongsheng@627: "manage stored passphrases." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:676 dongsheng@627: msgid "Configuring the server side properly" dongsheng@630: msgstr "正确配置服务器端" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:678 dongsheng@627: msgid "" dongsheng@627: "Because ssh can be fiddly to set up if you're new to it, there's a variety of " dongsheng@627: "things that can go wrong. Add Mercurial on top, and there's plenty more " dongsheng@627: "scope for head-scratching. Most of these potential problems occur on the " dongsheng@627: "server side, not the client side. The good news is that once you've gotten a " dongsheng@627: "configuration working, it will usually continue to work indefinitely." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:686 dongsheng@627: msgid "" dongsheng@627: "Before you try using Mercurial to talk to an ssh server, it's best to make " dongsheng@627: "sure that you can use the normal <command>ssh</command> or <command>putty</" dongsheng@627: "command> command to talk to the server first. If you run into problems with " dongsheng@627: "using these commands directly, Mercurial surely won't work. Worse, it will " dongsheng@627: "obscure the underlying problem. Any time you want to debug ssh-related " dongsheng@627: "Mercurial problems, you should drop back to making sure that plain ssh client " dongsheng@627: "commands work first, <emphasis>before</emphasis> you worry about whether " dongsheng@627: "there's a problem with Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:697 dongsheng@627: msgid "" dongsheng@627: "The first thing to be sure of on the server side is that you can actually log " dongsheng@627: "in from another machine at all. If you can't use <command>ssh</command> or " dongsheng@627: "<command>putty</command> to log in, the error message you get may give you a " dongsheng@627: "few hints as to what's wrong. The most common problems are as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:704 dongsheng@627: msgid "" dongsheng@627: "If you get a <quote>connection refused</quote> error, either there isn't an " dongsheng@627: "SSH daemon running on the server at all, or it's inaccessible due to firewall " dongsheng@627: "configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:709 dongsheng@627: msgid "" dongsheng@627: "If you get a <quote>no route to host</quote> error, you either have an " dongsheng@627: "incorrect address for the server or a seriously locked down firewall that " dongsheng@627: "won't admit its existence at all." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:714 dongsheng@627: msgid "" dongsheng@627: "If you get a <quote>permission denied</quote> error, you may have mistyped " dongsheng@627: "the username on the server, or you could have mistyped your key's passphrase " dongsheng@627: "or the remote user's password." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:719 dongsheng@627: msgid "" dongsheng@627: "In summary, if you're having trouble talking to the server's ssh daemon, " dongsheng@627: "first make sure that one is running at all. On many systems it will be " dongsheng@627: "installed, but disabled, by default. Once you're done with this step, you " dongsheng@627: "should then check that the server's firewall is configured to allow incoming " dongsheng@627: "connections on the port the ssh daemon is listening on (usually 22). Don't " dongsheng@627: "worry about more exotic possibilities for misconfiguration until you've " dongsheng@627: "checked these two first." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:729 dongsheng@627: msgid "" dongsheng@627: "If you're using an authentication agent on the client side to store " dongsheng@627: "passphrases for your keys, you ought to be able to log into the server " dongsheng@627: "without being prompted for a passphrase or a password. If you're prompted " dongsheng@627: "for a passphrase, there are a few possible culprits." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:735 dongsheng@627: msgid "" dongsheng@627: "You might have forgotten to use <command>ssh-add</command> or " dongsheng@627: "<command>pageant</command> to store the passphrase." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:739 dongsheng@627: msgid "You might have stored the passphrase for the wrong key." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:742 dongsheng@627: msgid "" dongsheng@627: "If you're being prompted for the remote user's password, there are another " dongsheng@627: "few possible problems to check." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:745 dongsheng@627: msgid "" dongsheng@627: "Either the user's home directory or their <filename role=\"special\" class=" dongsheng@627: "\"directory\">.ssh</filename> directory might have excessively liberal " dongsheng@627: "permissions. As a result, the ssh daemon will not trust or read their " dongsheng@627: "<filename role=\"special\">authorized_keys</filename> file. For example, a " dongsheng@627: "group-writable home or <filename role=\"special\" class=\"directory\">.ssh</" dongsheng@627: "filename> directory will often cause this symptom." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:754 dongsheng@627: msgid "" dongsheng@627: "The user's <filename role=\"special\">authorized_keys</filename> file may " dongsheng@627: "have a problem. If anyone other than the user owns or can write to that file, " dongsheng@627: "the ssh daemon will not trust or read it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:761 dongsheng@627: msgid "" dongsheng@627: "In the ideal world, you should be able to run the following command " dongsheng@627: "successfully, and it should print exactly one line of output, the current " dongsheng@627: "date and time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:766 dongsheng@627: msgid "" dongsheng@627: "If, on your server, you have login scripts that print banners or other junk " dongsheng@627: "even when running non-interactive commands like this, you should fix them " dongsheng@627: "before you continue, so that they only print output if they're run " dongsheng@627: "interactively. Otherwise these banners will at least clutter up Mercurial's " dongsheng@627: "output. Worse, they could potentially cause problems with running Mercurial " dongsheng@627: "commands remotely. Mercurial makes tries to detect and ignore banners in non-" dongsheng@627: "interactive <command>ssh</command> sessions, but it is not foolproof. (If " dongsheng@627: "you're editing your login scripts on your server, the usual way to see if a " dongsheng@627: "login script is running in an interactive shell is to check the return code " dongsheng@627: "from the command <literal>tty -s</literal>.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:780 dongsheng@627: msgid "" dongsheng@627: "Once you've verified that plain old ssh is working with your server, the next " dongsheng@627: "step is to ensure that Mercurial runs on the server. The following command " dongsheng@627: "should run successfully:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:785 dongsheng@627: msgid "" dongsheng@627: "If you see an error message instead of normal <command role=\"hg-cmd\">hg " dongsheng@627: "version</command> output, this is usually because you haven't installed " dongsheng@627: "Mercurial to <filename class=\"directory\">/usr/bin</filename>. Don't worry " dongsheng@627: "if this is the case; you don't need to do that. But you should check for a " dongsheng@627: "few possible problems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:792 dongsheng@627: msgid "" dongsheng@627: "Is Mercurial really installed on the server at all? I know this sounds " dongsheng@627: "trivial, but it's worth checking!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:796 dongsheng@627: msgid "" dongsheng@627: "Maybe your shell's search path (usually set via the <envar>PATH</envar> " dongsheng@627: "environment variable) is simply misconfigured." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:800 dongsheng@627: msgid "" dongsheng@627: "Perhaps your <envar>PATH</envar> environment variable is only being set to " dongsheng@627: "point to the location of the <command>hg</command> executable if the login " dongsheng@627: "session is interactive. This can happen if you're setting the path in the " dongsheng@627: "wrong shell login script. See your shell's documentation for details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:807 dongsheng@627: msgid "" dongsheng@627: "The <envar>PYTHONPATH</envar> environment variable may need to contain the " dongsheng@627: "path to the Mercurial Python modules. It might not be set at all; it could " dongsheng@627: "be incorrect; or it may be set only if the login is interactive." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:814 dongsheng@627: msgid "" dongsheng@627: "If you can run <command role=\"hg-cmd\">hg version</command> over an ssh " dongsheng@627: "connection, well done! You've got the server and client sorted out. You " dongsheng@627: "should now be able to use Mercurial to access repositories hosted by that " dongsheng@627: "username on that server. If you run into problems with Mercurial and ssh at " dongsheng@627: "this point, try using the <option role=\"hg-opt-global\">--debug</option> " dongsheng@627: "option to get a clearer picture of what's going on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:824 dongsheng@627: msgid "Using compression with ssh" dongsheng@630: msgstr "通过 ssh 使用压缩" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:826 dongsheng@627: msgid "" dongsheng@627: "Mercurial does not compress data when it uses the ssh protocol, because the " dongsheng@627: "ssh protocol can transparently compress data. However, the default behaviour " dongsheng@627: "of ssh clients is <emphasis>not</emphasis> to request compression." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:831 dongsheng@627: msgid "" dongsheng@627: "Over any network other than a fast LAN (even a wireless network), using " dongsheng@627: "compression is likely to significantly speed up Mercurial's network " dongsheng@627: "operations. For example, over a WAN, someone measured compression as " dongsheng@627: "reducing the amount of time required to clone a particularly large repository " dongsheng@627: "from 51 minutes to 17 minutes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:838 dongsheng@627: msgid "" dongsheng@627: "Both <command>ssh</command> and <command>plink</command> accept a <option " dongsheng@627: "role=\"cmd-opt-ssh\">-C</option> option which turns on compression. You can " dongsheng@627: "easily edit your <filename role=\"special\"> /.hgrc</filename>\\ to enable " dongsheng@627: "compression for all of Mercurial's uses of the ssh protocol." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:845 dongsheng@627: msgid "" dongsheng@627: "If you use <command>ssh</command>, you can configure it to always use " dongsheng@627: "compression when talking to your server. To do this, edit your <filename " dongsheng@627: "role=\"special\">.ssh/config</filename> file (which may not yet exist), as " dongsheng@627: "follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:852 dongsheng@627: msgid "" dongsheng@627: "This defines an alias, <literal>hg</literal>. When you use it on the " dongsheng@627: "<command>ssh</command> command line or in a Mercurial <literal>ssh</literal>-" dongsheng@627: "protocol URL, it will cause <command>ssh</command> to connect to <literal>hg." dongsheng@627: "example.com</literal> and use compression. This gives you both a shorter " dongsheng@627: "name to type and compression, each of which is a good thing in its own right." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:863 dongsheng@627: msgid "Serving over HTTP using CGI" dongsheng@630: msgstr "使用 CGI 通过 HTTP 提供服务" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:865 dongsheng@627: msgid "" dongsheng@627: "Depending on how ambitious you are, configuring Mercurial's CGI interface can " dongsheng@627: "take anything from a few moments to several hours." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:869 dongsheng@627: msgid "" dongsheng@627: "We'll begin with the simplest of examples, and work our way towards a more " dongsheng@627: "complex configuration. Even for the most basic case, you're almost certainly " dongsheng@627: "going to need to read and modify your web server's configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch06-collab.xml:875 dongsheng@627: msgid "" dongsheng@627: "Configuring a web server is a complex, fiddly, and highly system-dependent " dongsheng@627: "activity. I can't possibly give you instructions that will cover anything " dongsheng@627: "like all of the cases you will encounter. Please use your discretion and " dongsheng@627: "judgment in following the sections below. Be prepared to make plenty of " dongsheng@627: "mistakes, and to spend a lot of time reading your server's error logs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:885 dongsheng@627: msgid "Web server configuration checklist" dongsheng@630: msgstr "Web 服务器配置检查表" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:887 dongsheng@627: msgid "" dongsheng@627: "Before you continue, do take a few moments to check a few aspects of your " dongsheng@627: "system's setup." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:891 dongsheng@627: msgid "" dongsheng@627: "Do you have a web server installed at all? Mac OS X ships with Apache, but " dongsheng@627: "many other systems may not have a web server installed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:895 dongsheng@627: msgid "" dongsheng@627: "If you have a web server installed, is it actually running? On most systems, " dongsheng@627: "even if one is present, it will be disabled by default." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:899 dongsheng@627: msgid "" dongsheng@627: "Is your server configured to allow you to run CGI programs in the directory " dongsheng@627: "where you plan to do so? Most servers default to explicitly disabling the " dongsheng@627: "ability to run CGI programs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:905 dongsheng@627: msgid "" dongsheng@627: "If you don't have a web server installed, and don't have substantial " dongsheng@627: "experience configuring Apache, you should consider using the " dongsheng@627: "<literal>lighttpd</literal> web server instead of Apache. Apache has a well-" dongsheng@627: "deserved reputation for baroque and confusing configuration. While " dongsheng@627: "<literal>lighttpd</literal> is less capable in some ways than Apache, most of " dongsheng@627: "these capabilities are not relevant to serving Mercurial repositories. And " dongsheng@627: "<literal>lighttpd</literal> is undeniably <emphasis>much</emphasis> easier to " dongsheng@627: "get started with than Apache." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:918 dongsheng@627: msgid "Basic CGI configuration" dongsheng@630: msgstr "基本 CGI 配置" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:920 dongsheng@627: msgid "" dongsheng@627: "On Unix-like systems, it's common for users to have a subdirectory named " dongsheng@627: "something like <filename class=\"directory\">public_html</filename> in their " dongsheng@627: "home directory, from which they can serve up web pages. A file named " dongsheng@627: "<filename>foo</filename> in this directory will be accessible at a URL of the " dongsheng@627: "form <literal>http://www.example.com/\\ {</literal>username/foo}." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:929 dongsheng@627: msgid "" dongsheng@627: "To get started, find the <filename role=\"special\">hgweb.cgi</filename> " dongsheng@627: "script that should be present in your Mercurial installation. If you can't " dongsheng@627: "quickly find a local copy on your system, simply download one from the master " dongsheng@627: "Mercurial repository at <ulink url=\"http://www.selenic.com/repo/hg/raw-file/" dongsheng@627: "tip/hgweb.cgi\">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:936 ../en/ch06-collab.xml:1109 dongsheng@627: msgid "" dongsheng@627: "You'll need to copy this script into your <filename class=\"directory" dongsheng@627: "\">public_html</filename> directory, and ensure that it's executable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:941 dongsheng@627: msgid "" dongsheng@627: "The <literal>755</literal> argument to <command>chmod</command> is a little " dongsheng@627: "more general than just making the script executable: it ensures that the " dongsheng@627: "script is executable by anyone, and that <quote>group</quote> and " dongsheng@627: "<quote>other</quote> write permissions are <emphasis>not</emphasis> set. If " dongsheng@627: "you were to leave those write permissions enabled, Apache's <literal>suexec</" dongsheng@627: "literal> subsystem would likely refuse to execute the script. In fact, " dongsheng@627: "<literal>suexec</literal> also insists that the <emphasis>directory</" dongsheng@627: "emphasis> in which the script resides must not be writable by others." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:955 dongsheng@627: msgid "What could <emphasis>possibly</emphasis> go wrong?" dongsheng@630: msgstr "什么<emphasis>可能</emphasis>会出错?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:958 dongsheng@627: msgid "" dongsheng@627: "Once you've copied the CGI script into place, go into a web browser, and try " dongsheng@627: "to open the URL <ulink url=\"http://myhostname/ myuser/hgweb.cgi\">http://" dongsheng@627: "myhostname/ myuser/hgweb.cgi</ulink>, <emphasis>but</emphasis> brace yourself " dongsheng@627: "for instant failure. There's a high probability that trying to visit this " dongsheng@627: "URL will fail, and there are many possible reasons for this. In fact, you're " dongsheng@627: "likely to stumble over almost every one of the possible errors below, so " dongsheng@627: "please read carefully. The following are all of the problems I ran into on a " dongsheng@627: "system running Fedora 7, with a fresh installation of Apache, and a user " dongsheng@627: "account that I created specially to perform this exercise." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:972 dongsheng@627: msgid "" dongsheng@627: "Your web server may have per-user directories disabled. If you're using " dongsheng@627: "Apache, search your config file for a <literal>UserDir</literal> directive. " dongsheng@627: "If there's none present, per-user directories will be disabled. If one " dongsheng@627: "exists, but its value is <literal>disabled</literal>, then per-user " dongsheng@627: "directories will be disabled. Otherwise, the string after <literal>UserDir</" dongsheng@627: "literal> gives the name of the subdirectory that Apache will look in under " dongsheng@627: "your home directory, for example <filename class=\"directory\">public_html</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:983 dongsheng@627: msgid "" dongsheng@627: "Your file access permissions may be too restrictive. The web server must be " dongsheng@627: "able to traverse your home directory and directories under your <filename " dongsheng@627: "class=\"directory\">public_html</filename> directory, and read files under " dongsheng@627: "the latter too. Here's a quick recipe to help you to make your permissions " dongsheng@627: "more appropriate." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:993 dongsheng@627: msgid "" dongsheng@627: "The other possibility with permissions is that you might get a completely " dongsheng@627: "empty window when you try to load the script. In this case, it's likely that " dongsheng@627: "your access permissions are <emphasis>too permissive</emphasis>. Apache's " dongsheng@627: "<literal>suexec</literal> subsystem won't execute a script that's group- or " dongsheng@627: "world-writable, for example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1000 dongsheng@627: msgid "" dongsheng@627: "Your web server may be configured to disallow execution of CGI programs in " dongsheng@627: "your per-user web directory. Here's Apache's default per-user configuration " dongsheng@627: "from my Fedora system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1011 dongsheng@627: msgid "" dongsheng@627: "If you find a similar-looking <literal>Directory</literal> group in your " dongsheng@627: "Apache configuration, the directive to look at inside it is <literal>Options</" dongsheng@627: "literal>. Add <literal>ExecCGI</literal> to the end of this list if it's " dongsheng@627: "missing, and restart the web server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1018 dongsheng@627: msgid "" dongsheng@627: "If you find that Apache serves you the text of the CGI script instead of " dongsheng@627: "executing it, you may need to either uncomment (if already present) or add a " dongsheng@627: "directive like this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1024 dongsheng@627: msgid "" dongsheng@627: "The next possibility is that you might be served with a colourful Python " dongsheng@627: "backtrace claiming that it can't import a <literal>mercurial</literal>-" dongsheng@627: "related module. This is actually progress! The server is now capable of " dongsheng@627: "executing your CGI script. This error is only likely to occur if you're " dongsheng@627: "running a private installation of Mercurial, instead of a system-wide " dongsheng@627: "version. Remember that the web server runs the CGI program without any of " dongsheng@627: "the environment variables that you take for granted in an interactive " dongsheng@627: "session. If this error happens to you, edit your copy of <filename role=" dongsheng@627: "\"special\">hgweb.cgi</filename> and follow the directions inside it to " dongsheng@627: "correctly set your <envar>PYTHONPATH</envar> environment variable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1038 dongsheng@627: msgid "" dongsheng@627: "Finally, you are <emphasis>certain</emphasis> to by served with another " dongsheng@627: "colourful Python backtrace: this one will complain that it can't find " dongsheng@627: "<filename class=\"directory\">/path/to/repository</filename>. Edit your " dongsheng@627: "<filename role=\"special\">hgweb.cgi</filename> script and replace the " dongsheng@627: "<filename class=\"directory\">/path/to/repository</filename> string with the " dongsheng@627: "complete path to the repository you want to serve up." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1048 dongsheng@627: msgid "" dongsheng@627: "At this point, when you try to reload the page, you should be presented with " dongsheng@627: "a nice HTML view of your repository's history. Whew!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1054 dongsheng@627: msgid "Configuring lighttpd" dongsheng@630: msgstr "配置 lighttpd" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1056 dongsheng@627: msgid "" dongsheng@627: "To be exhaustive in my experiments, I tried configuring the increasingly " dongsheng@627: "popular <literal>lighttpd</literal> web server to serve the same repository " dongsheng@627: "as I described with Apache above. I had already overcome all of the problems " dongsheng@627: "I outlined with Apache, many of which are not server-specific. As a result, " dongsheng@627: "I was fairly sure that my file and directory permissions were good, and that " dongsheng@627: "my <filename role=\"special\">hgweb.cgi</filename> script was properly edited." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1066 dongsheng@627: msgid "" dongsheng@627: "Once I had Apache running, getting <literal>lighttpd</literal> to serve the " dongsheng@627: "repository was a snap (in other words, even if you're trying to use " dongsheng@627: "<literal>lighttpd</literal>, you should read the Apache section). I first " dongsheng@627: "had to edit the <literal>mod_access</literal> section of its config file to " dongsheng@627: "enable <literal>mod_cgi</literal> and <literal>mod_userdir</literal>, both of " dongsheng@627: "which were disabled by default on my system. I then added a few lines to the " dongsheng@627: "end of the config file, to configure these modules." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1078 dongsheng@627: msgid "" dongsheng@627: "With this done, <literal>lighttpd</literal> ran immediately for me. If I had " dongsheng@627: "configured <literal>lighttpd</literal> before Apache, I'd almost certainly " dongsheng@627: "have run into many of the same system-level configuration problems as I did " dongsheng@627: "with Apache. However, I found <literal>lighttpd</literal> to be noticeably " dongsheng@627: "easier to configure than Apache, even though I've used Apache for over a " dongsheng@627: "decade, and this was my first exposure to <literal>lighttpd</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:1091 dongsheng@627: msgid "Sharing multiple repositories with one CGI script" dongsheng@630: msgstr "使用一个 CGI 脚本共享多个版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1093 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">hgweb.cgi</filename> script only lets you " dongsheng@627: "publish a single repository, which is an annoying restriction. If you want " dongsheng@627: "to publish more than one without wracking yourself with multiple copies of " dongsheng@627: "the same script, each with different names, a better choice is to use the " dongsheng@627: "<filename role=\"special\">hgwebdir.cgi</filename> script." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1101 dongsheng@627: msgid "" dongsheng@627: "The procedure to configure <filename role=\"special\">hgwebdir.cgi</filename> " dongsheng@627: "is only a little more involved than for <filename role=\"special\">hgweb.cgi</" dongsheng@627: "filename>. First, you must obtain a copy of the script. If you don't have " dongsheng@627: "one handy, you can download a copy from the master Mercurial repository at " dongsheng@627: "<ulink url=\"http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi" dongsheng@627: "\">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1114 dongsheng@627: msgid "" dongsheng@627: "With basic configuration out of the way, try to visit <ulink url=\"http://" dongsheng@627: "myhostname/ myuser/hgwebdir.cgi\">http://myhostname/ myuser/hgwebdir.cgi</" dongsheng@627: "ulink> in your browser. It should display an empty list of repositories. If " dongsheng@627: "you get a blank window or error message, try walking through the list of " dongsheng@627: "potential problems in section <xref linkend=\"sec.collab.wtf\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1123 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">hgwebdir.cgi</filename> script relies on an " dongsheng@627: "external configuration file. By default, it searches for a file named " dongsheng@627: "<filename role=\"special\">hgweb.config</filename> in the same directory as " dongsheng@627: "itself. You'll need to create this file, and make it world-readable. The " dongsheng@627: "format of the file is similar to a Windows <quote>ini</quote> file, as " dongsheng@627: "understood by Python's <literal>ConfigParser</literal> <citation>web:" dongsheng@627: "configparser</citation> module." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1133 dongsheng@627: msgid "" dongsheng@627: "The easiest way to configure <filename role=\"special\">hgwebdir.cgi</" dongsheng@627: "filename> is with a section named <literal>collections</literal>. This will " dongsheng@627: "automatically publish <emphasis>every</emphasis> repository under the " dongsheng@627: "directories you name. The section should look like this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1141 dongsheng@627: msgid "" dongsheng@627: "Mercurial interprets this by looking at the directory name on the " dongsheng@627: "<emphasis>right</emphasis> hand side of the <quote><literal>=</literal></" dongsheng@627: "quote> sign; finding repositories in that directory hierarchy; and using the " dongsheng@627: "text on the <emphasis>left</emphasis> to strip off matching text from the " dongsheng@627: "names it will actually list in the web interface. The remaining component of " dongsheng@627: "a path after this stripping has occurred is called a <quote>virtual path</" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1150 dongsheng@627: msgid "" dongsheng@627: "Given the example above, if we have a repository whose local path is " dongsheng@627: "<filename class=\"directory\">/my/root/this/repo</filename>, the CGI script " dongsheng@627: "will strip the leading <filename class=\"directory\">/my/root</filename> from " dongsheng@627: "the name, and publish the repository with a virtual path of <filename class=" dongsheng@627: "\"directory\">this/repo</filename>. If the base URL for our CGI script is " dongsheng@627: "<ulink url=\"http://myhostname/ myuser/hgwebdir.cgi\">http://myhostname/ " dongsheng@627: "myuser/hgwebdir.cgi</ulink>, the complete URL for that repository will be " dongsheng@627: "<ulink url=\"http://myhostname/ myuser/hgwebdir.cgi/this/repo\">http://" dongsheng@627: "myhostname/ myuser/hgwebdir.cgi/this/repo</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1164 dongsheng@627: msgid "" dongsheng@627: "If we replace <filename class=\"directory\">/my/root</filename> on the left " dongsheng@627: "hand side of this example with <filename class=\"directory\">/my</filename>, " dongsheng@627: "then <filename role=\"special\">hgwebdir.cgi</filename> will only strip off " dongsheng@627: "<filename class=\"directory\">/my</filename> from the repository name, and " dongsheng@627: "will give us a virtual path of <filename class=\"directory\">root/this/repo</" dongsheng@627: "filename> instead of <filename class=\"directory\">this/repo</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1174 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">hgwebdir.cgi</filename> script will " dongsheng@627: "recursively search each directory listed in the <literal>collections</" dongsheng@627: "literal> section of its configuration file, but it will <literal>not</" dongsheng@627: "literal> recurse into the repositories it finds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1180 dongsheng@627: msgid "" dongsheng@627: "The <literal>collections</literal> mechanism makes it easy to publish many " dongsheng@627: "repositories in a <quote>fire and forget</quote> manner. You only need to " dongsheng@627: "set up the CGI script and configuration file one time. Afterwards, you can " dongsheng@627: "publish or unpublish a repository at any time by simply moving it into, or " dongsheng@627: "out of, the directory hierarchy in which you've configured <filename role=" dongsheng@627: "\"special\">hgwebdir.cgi</filename> to look." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1190 dongsheng@627: msgid "Explicitly specifying which repositories to publish" dongsheng@630: msgstr "明确指出要发布的版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1193 dongsheng@627: msgid "" dongsheng@627: "In addition to the <literal>collections</literal> mechanism, the <filename " dongsheng@627: "role=\"special\">hgwebdir.cgi</filename> script allows you to publish a " dongsheng@627: "specific list of repositories. To do so, create a <literal>paths</literal> " dongsheng@627: "section, with contents of the following form." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1201 dongsheng@627: msgid "" dongsheng@627: "In this case, the virtual path (the component that will appear in a URL) is " dongsheng@627: "on the left hand side of each definition, while the path to the repository is " dongsheng@627: "on the right. Notice that there does not need to be any relationship between " dongsheng@627: "the virtual path you choose and the location of a repository in your " dongsheng@627: "filesystem." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1208 dongsheng@627: msgid "" dongsheng@627: "If you wish, you can use both the <literal>collections</literal> and " dongsheng@627: "<literal>paths</literal> mechanisms simultaneously in a single configuration " dongsheng@627: "file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><note><para> dongsheng@627: #: ../en/ch06-collab.xml:1214 dongsheng@627: msgid "" dongsheng@627: "If multiple repositories have the same virtual path, <filename role=\"special" dongsheng@627: "\">hgwebdir.cgi</filename> will not report an error. Instead, it will behave " dongsheng@627: "unpredictably." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:1223 dongsheng@627: msgid "Downloading source archives" dongsheng@630: msgstr "下载源代码档案包" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1225 dongsheng@627: msgid "" dongsheng@627: "Mercurial's web interface lets users download an archive of any revision. " dongsheng@627: "This archive will contain a snapshot of the working directory as of that " dongsheng@627: "revision, but it will not contain a copy of the repository data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1230 dongsheng@627: msgid "" dongsheng@627: "By default, this feature is not enabled. To enable it, you'll need to add an " dongsheng@627: "<envar role=\"rc-item-web\">allow_archive</envar> item to the <literal role=" dongsheng@627: "\"rc-web\">web</literal> section of your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:1238 dongsheng@627: msgid "Web configuration options" dongsheng@630: msgstr "Web 配置选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1240 dongsheng@627: msgid "" dongsheng@627: "Mercurial's web interfaces (the <command role=\"hg-cmd\">hg serve</command> " dongsheng@627: "command, and the <filename role=\"special\">hgweb.cgi</filename> and " dongsheng@627: "<filename role=\"special\">hgwebdir.cgi</filename> scripts) have a number of " dongsheng@627: "configuration options that you can set. These belong in a section named " dongsheng@627: "<literal role=\"rc-web\">web</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1248 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">allow_archive</envar>: Determines which (if any) " dongsheng@627: "archive download mechanisms Mercurial supports. If you enable this feature, " dongsheng@627: "users of the web interface will be able to download an archive of whatever " dongsheng@627: "revision of a repository they are viewing. To enable the archive feature, " dongsheng@627: "this item must take the form of a sequence of words drawn from the list below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1257 dongsheng@627: msgid "" dongsheng@627: "<literal>bz2</literal>: A <command>tar</command> archive, compressed using " dongsheng@627: "<literal>bzip2</literal> compression. This has the best compression ratio, " dongsheng@627: "but uses the most CPU time on the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1263 dongsheng@627: msgid "" dongsheng@627: "<literal>gz</literal>: A <command>tar</command> archive, compressed using " dongsheng@627: "<literal>gzip</literal> compression." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1267 dongsheng@627: msgid "" dongsheng@627: "<literal>zip</literal>: A <command>zip</command> archive, compressed using " dongsheng@627: "LZW compression. This format has the worst compression ratio, but is widely " dongsheng@627: "used in the Windows world." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1273 dongsheng@627: msgid "" dongsheng@627: "If you provide an empty list, or don't have an <envar role=\"rc-item-web" dongsheng@627: "\">allow_archive</envar> entry at all, this feature will be disabled. Here " dongsheng@627: "is an example of how to enable all three supported formats." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1280 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">allowpull</envar>: Boolean. Determines whether " dongsheng@627: "the web interface allows remote users to <command role=\"hg-cmd\">hg pull</" dongsheng@627: "command> and <command role=\"hg-cmd\">hg clone</command> this repository over " dongsheng@627: "HTTP. If set to <literal>no</literal> or <literal>false</literal>, only the " dongsheng@627: "<quote>human-oriented</quote> portion of the web interface is available." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1289 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">contact</envar>: String. A free-form (but " dongsheng@627: "preferably brief) string identifying the person or group in charge of the " dongsheng@627: "repository. This often contains the name and email address of a person or " dongsheng@627: "mailing list. It often makes sense to place this entry in a repository's own " dongsheng@627: "<filename role=\"special\">.hg/hgrc</filename> file, but it can make sense to " dongsheng@627: "use in a global <filename role=\"special\"> /.hgrc</filename>\\ if every " dongsheng@627: "repository has a single maintainer." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1300 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">maxchanges</envar>: Integer. The default maximum " dongsheng@627: "number of changesets to display in a single page of output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1304 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">maxfiles</envar>: Integer. The default maximum " dongsheng@627: "number of modified files to display in a single page of output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1308 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">stripes</envar>: Integer. If the web interface " dongsheng@627: "displays alternating <quote>stripes</quote> to make it easier to visually " dongsheng@627: "align rows when you are looking at a table, this number controls the number " dongsheng@627: "of rows in each stripe." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1314 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">style</envar>: Controls the template Mercurial " dongsheng@627: "uses to display the web interface. Mercurial ships with two web templates, " dongsheng@627: "named <literal>default</literal> and <literal>gitweb</literal> (the latter is " dongsheng@627: "much more visually attractive). You can also specify a custom template of " dongsheng@627: "your own; see chapter <xref linkend=\"chap.template\"/> for details. Here, " dongsheng@627: "you can see how to enable the <literal>gitweb</literal> style." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1325 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">templates</envar>: Path. The directory in which " dongsheng@627: "to search for template files. By default, Mercurial searches in the " dongsheng@627: "directory in which it was installed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1330 dongsheng@627: msgid "" dongsheng@627: "If you are using <filename role=\"special\">hgwebdir.cgi</filename>, you can " dongsheng@627: "place a few configuration items in a <literal role=\"rc-web\">web</literal> " dongsheng@627: "section of the <filename role=\"special\">hgweb.config</filename> file " dongsheng@627: "instead of a <filename role=\"special\"> /.hgrc</filename>\\ file, for " dongsheng@627: "convenience. These items are <envar role=\"rc-item-web\">motd</envar> and " dongsheng@627: "<envar role=\"rc-item-web\">style</envar>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1341 dongsheng@627: msgid "Options specific to an individual repository" dongsheng@630: msgstr "针对单个版本库的选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1343 dongsheng@627: msgid "" dongsheng@627: "A few <literal role=\"rc-web\">web</literal> configuration items ought to be " dongsheng@627: "placed in a repository's local <filename role=\"special\">.hg/hgrc</" dongsheng@627: "filename>, rather than a user's or global <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1349 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">description</envar>: String. A free-form (but " dongsheng@627: "preferably brief) string that describes the contents or purpose of the " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1354 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">name</envar>: String. The name to use for the " dongsheng@627: "repository in the web interface. This overrides the default name, which is " dongsheng@627: "the last component of the repository's path." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1362 dongsheng@627: msgid "" dongsheng@627: "Options specific to the <command role=\"hg-cmd\">hg serve</command> command" dongsheng@630: msgstr "命令 <command role=\"hg-cmd\">hg serve</command> 的选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1365 dongsheng@627: msgid "" dongsheng@627: "Some of the items in the <literal role=\"rc-web\">web</literal> section of a " dongsheng@627: "<filename role=\"special\"> /.hgrc</filename>\\ file are only for use with " dongsheng@627: "the <command role=\"hg-cmd\">hg serve</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1371 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">accesslog</envar>: Path. The name of a file into " dongsheng@627: "which to write an access log. By default, the <command role=\"hg-cmd\">hg " dongsheng@627: "serve</command> command writes this information to standard output, not to a " dongsheng@627: "file. Log entries are written in the standard <quote>combined</quote> file " dongsheng@627: "format used by almost all web servers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1379 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">address</envar>: String. The local address on " dongsheng@627: "which the server should listen for incoming connections. By default, the " dongsheng@627: "server listens on all addresses." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1384 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">errorlog</envar>: Path. The name of a file into " dongsheng@627: "which to write an error log. By default, the <command role=\"hg-cmd\">hg " dongsheng@627: "serve</command> command writes this information to standard error, not to a " dongsheng@627: "file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1390 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">ipv6</envar>: Boolean. Whether to use the IPv6 " dongsheng@627: "protocol. By default, IPv6 is not used." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1394 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">port</envar>: Integer. The TCP port number on " dongsheng@627: "which the server should listen. The default port number used is 8000." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1401 dongsheng@627: msgid "" dongsheng@627: "Choosing the right <filename role=\"special\"> /.hgrc</filename>\\ file to " dongsheng@627: "add <literal role=\"rc-web\">web</literal> items to" dongsheng@627: msgstr "" dongsheng@630: "选择正确的 <filename role=\"special\"> /.hgrc</filename> 文件增加到 <literal " dongsheng@630: "role=\"rc-web\">web</literal> 条目" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1405 dongsheng@627: msgid "" dongsheng@627: "It is important to remember that a web server like Apache or " dongsheng@627: "<literal>lighttpd</literal> will run under a user ID that is different to " dongsheng@627: "yours. CGI scripts run by your server, such as <filename role=\"special" dongsheng@627: "\">hgweb.cgi</filename>, will usually also run under that user ID." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1412 dongsheng@627: msgid "" dongsheng@627: "If you add <literal role=\"rc-web\">web</literal> items to your own personal " dongsheng@627: "<filename role=\"special\"> /.hgrc</filename>\\ file, CGI scripts won't read " dongsheng@627: "that <filename role=\"special\"> /.hgrc</filename>\\ file. Those settings " dongsheng@627: "will thus only affect the behaviour of the <command role=\"hg-cmd\">hg serve</" dongsheng@627: "command> command when you run it. To cause CGI scripts to see your settings, " dongsheng@627: "either create a <filename role=\"special\"> /.hgrc</filename>\\ file in the " dongsheng@627: "home directory of the user ID that runs your web server, or add those " dongsheng@627: "settings to a system-wide <filename role=\"special\"> /.hgrc</filename>\\ " dongsheng@627: "file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch07-filenames.xml:5 dongsheng@627: msgid "File names and pattern matching" dongsheng@627: msgstr "文件名称与模式匹配" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch07-filenames.xml:7 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides mechanisms that let you work with file names in a " dongsheng@627: "consistent and expressive way." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:11 dongsheng@627: msgid "Simple file naming" dongsheng@630: msgstr "简单文件名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:13 dongsheng@627: msgid "" dongsheng@627: "Mercurial uses a unified piece of machinery <quote>under the hood</quote> to " dongsheng@627: "handle file names. Every command behaves uniformly with respect to file " dongsheng@627: "names. The way in which commands work with file names is as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:18 dongsheng@627: msgid "" dongsheng@627: "If you explicitly name real files on the command line, Mercurial works with " dongsheng@627: "exactly those files, as you would expect. &interaction.filenames.files;" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:22 dongsheng@627: msgid "" dongsheng@627: "When you provide a directory name, Mercurial will interpret this as " dongsheng@627: "<quote>operate on every file in this directory and its subdirectories</" dongsheng@627: "quote>. Mercurial traverses the files and subdirectories in a directory in " dongsheng@627: "alphabetical order. When it encounters a subdirectory, it will traverse that " dongsheng@627: "subdirectory before continuing with the current directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:33 dongsheng@627: msgid "Running commands without any file names" dongsheng@630: msgstr "不提供文件名称的执行命令" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:35 dongsheng@627: msgid "" dongsheng@627: "Mercurial's commands that work with file names have useful default behaviours " dongsheng@627: "when you invoke them without providing any file names or patterns. What kind " dongsheng@627: "of behaviour you should expect depends on what the command does. Here are a " dongsheng@627: "few rules of thumb you can use to predict what a command is likely to do if " dongsheng@627: "you don't give it any names to work with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:42 dongsheng@627: msgid "" dongsheng@627: "Most commands will operate on the entire working directory. This is what the " dongsheng@627: "<command role=\"hg-cmd\">hg add</command> command does, for example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:46 dongsheng@627: msgid "" dongsheng@627: "If the command has effects that are difficult or impossible to reverse, it " dongsheng@627: "will force you to explicitly provide at least one name or pattern (see " dongsheng@627: "below). This protects you from accidentally deleting files by running " dongsheng@627: "<command role=\"hg-cmd\">hg remove</command> with no arguments, for example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:54 dongsheng@627: msgid "" dongsheng@627: "It's easy to work around these default behaviours if they don't suit you. If " dongsheng@627: "a command normally operates on the whole working directory, you can invoke it " dongsheng@627: "on just the current directory and its subdirectories by giving it the name " dongsheng@627: "<quote><filename class=\"directory\">.</filename></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:62 dongsheng@627: msgid "" dongsheng@627: "Along the same lines, some commands normally print file names relative to the " dongsheng@627: "root of the repository, even if you're invoking them from a subdirectory. " dongsheng@627: "Such a command will print file names relative to your subdirectory if you " dongsheng@627: "give it explicit names. Here, we're going to run <command role=\"hg-cmd\">hg " dongsheng@627: "status</command> from a subdirectory, and get it to operate on the entire " dongsheng@627: "working directory while printing file names relative to our subdirectory, by " dongsheng@627: "passing it the output of the <command role=\"hg-cmd\">hg root</command> " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:76 dongsheng@627: msgid "Telling you what's going on" dongsheng@630: msgstr "告诉你正在做什么" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:78 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg add</command> example in the preceding " dongsheng@627: "section illustrates something else that's helpful about Mercurial commands. " dongsheng@627: "If a command operates on a file that you didn't name explicitly on the " dongsheng@627: "command line, it will usually print the name of the file, so that you will " dongsheng@627: "not be surprised what's going on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:85 dongsheng@627: msgid "" dongsheng@627: "The principle here is of <emphasis>least surprise</emphasis>. If you've " dongsheng@627: "exactly named a file on the command line, there's no point in repeating it " dongsheng@627: "back at you. If Mercurial is acting on a file <emphasis>implicitly</" dongsheng@627: "emphasis>, because you provided no names, or a directory, or a pattern (see " dongsheng@627: "below), it's safest to tell you what it's doing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:92 dongsheng@627: msgid "" dongsheng@627: "For commands that behave this way, you can silence them using the <option " dongsheng@627: "role=\"hg-opt-global\">-q</option> option. You can also get them to print " dongsheng@627: "the name of every file, even those you've named explicitly, using the <option " dongsheng@627: "role=\"hg-opt-global\">-v</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:100 dongsheng@627: msgid "Using patterns to identify files" dongsheng@630: msgstr "使用模式标识文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:102 dongsheng@627: msgid "" dongsheng@627: "In addition to working with file and directory names, Mercurial lets you use " dongsheng@627: "<emphasis>patterns</emphasis> to identify files. Mercurial's pattern " dongsheng@627: "handling is expressive." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:106 dongsheng@627: msgid "" dongsheng@627: "On Unix-like systems (Linux, MacOS, etc.), the job of matching file names to " dongsheng@627: "patterns normally falls to the shell. On these systems, you must explicitly " dongsheng@627: "tell Mercurial that a name is a pattern. On Windows, the shell does not " dongsheng@627: "expand patterns, so Mercurial will automatically identify names that are " dongsheng@627: "patterns, and expand them for you." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:113 dongsheng@627: msgid "" dongsheng@627: "To provide a pattern in place of a regular name on the command line, the " dongsheng@627: "mechanism is simple:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:116 dongsheng@627: msgid "" dongsheng@627: "That is, a pattern is identified by a short text string that says what kind " dongsheng@627: "of pattern this is, followed by a colon, followed by the actual pattern." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:120 dongsheng@627: msgid "" dongsheng@627: "Mercurial supports two kinds of pattern syntax. The most frequently used is " dongsheng@627: "called <literal>glob</literal>; this is the same kind of pattern matching " dongsheng@627: "used by the Unix shell, and should be familiar to Windows command prompt " dongsheng@627: "users, too." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:125 dongsheng@627: msgid "" dongsheng@627: "When Mercurial does automatic pattern matching on Windows, it uses " dongsheng@627: "<literal>glob</literal> syntax. You can thus omit the <quote><literal>glob:</" dongsheng@627: "literal></quote> prefix on Windows, but it's safe to use it, too." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:130 dongsheng@627: msgid "" dongsheng@627: "The <literal>re</literal> syntax is more powerful; it lets you specify " dongsheng@627: "patterns using regular expressions, also known as regexps." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:134 dongsheng@627: msgid "" dongsheng@627: "By the way, in the examples that follow, notice that I'm careful to wrap all " dongsheng@627: "of my patterns in quote characters, so that they won't get expanded by the " dongsheng@627: "shell before Mercurial sees them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:140 dongsheng@627: msgid "Shell-style <literal>glob</literal> patterns" dongsheng@630: msgstr "外壳风格的 <literal>glob</literal> 模式" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:142 dongsheng@627: msgid "" dongsheng@627: "This is an overview of the kinds of patterns you can use when you're matching " dongsheng@627: "on glob patterns." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:145 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>*</literal></quote> character matches any string, within " dongsheng@627: "a single directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:150 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>**</literal></quote> pattern matches any string, and " dongsheng@627: "crosses directory boundaries. It's not a standard Unix glob token, but it's " dongsheng@627: "accepted by several popular Unix shells, and is very useful." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:157 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>?</literal></quote> pattern matches any single character." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:162 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>[</literal></quote> character begins a " dongsheng@627: "<emphasis>character class</emphasis>. This matches any single character " dongsheng@627: "within the class. The class ends with a <quote><literal>]</literal></quote> " dongsheng@627: "character. A class may contain multiple <emphasis>range</emphasis>s of the " dongsheng@627: "form <quote><literal>a-f</literal></quote>, which is shorthand for " dongsheng@627: "<quote><literal>abcdef</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:172 dongsheng@627: msgid "" dongsheng@627: "If the first character after the <quote><literal>[</literal></quote> in a " dongsheng@627: "character class is a <quote><literal>!</literal></quote>, it " dongsheng@627: "<emphasis>negates</emphasis> the class, making it match any single character " dongsheng@627: "not in the class." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:178 dongsheng@627: msgid "" dongsheng@627: "A <quote><literal>{</literal></quote> begins a group of subpatterns, where " dongsheng@627: "the whole group matches if any subpattern in the group matches. The " dongsheng@627: "<quote><literal>,</literal></quote> character separates subpatterns, and " dongsheng@627: "<quote><literal>}</literal></quote> ends the group." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch07-filenames.xml:187 dongsheng@627: msgid "Watch out!" dongsheng@630: msgstr "千万小心！" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch07-filenames.xml:189 dongsheng@627: msgid "" dongsheng@627: "Don't forget that if you want to match a pattern in any directory, you should " dongsheng@627: "not be using the <quote><literal>*</literal></quote> match-any token, as this " dongsheng@627: "will only match within one directory. Instead, use the <quote><literal>**</" dongsheng@627: "literal></quote> token. This small example illustrates the difference " dongsheng@627: "between the two." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:201 dongsheng@627: msgid "Regular expression matching with <literal>re</literal> patterns" dongsheng@630: msgstr "使用 <literal>re</literal> 模式的正则表达式匹配" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:204 dongsheng@627: msgid "" dongsheng@627: "Mercurial accepts the same regular expression syntax as the Python " dongsheng@627: "programming language (it uses Python's regexp engine internally). This is " dongsheng@627: "based on the Perl language's regexp syntax, which is the most popular dialect " dongsheng@627: "in use (it's also used in Java, for example)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:210 dongsheng@627: msgid "" dongsheng@627: "I won't discuss Mercurial's regexp dialect in any detail here, as regexps are " dongsheng@627: "not often used. Perl-style regexps are in any case already exhaustively " dongsheng@627: "documented on a multitude of web sites, and in many books. Instead, I will " dongsheng@627: "focus here on a few things you should know if you find yourself needing to " dongsheng@627: "use regexps with Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:217 dongsheng@627: msgid "" dongsheng@627: "A regexp is matched against an entire file name, relative to the root of the " dongsheng@627: "repository. In other words, even if you're already in subbdirectory " dongsheng@627: "<filename class=\"directory\">foo</filename>, if you want to match files " dongsheng@627: "under this directory, your pattern must start with <quote><literal>foo/</" dongsheng@627: "literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:224 dongsheng@627: msgid "" dongsheng@627: "One thing to note, if you're familiar with Perl-style regexps, is that " dongsheng@627: "Mercurial's are <emphasis>rooted</emphasis>. That is, a regexp starts " dongsheng@627: "matching against the beginning of a string; it doesn't look for a match " dongsheng@627: "anywhere within the string. To match anywhere in a string, start your " dongsheng@627: "pattern with <quote><literal>.*</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:234 dongsheng@627: msgid "Filtering files" dongsheng@630: msgstr "过滤文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:236 dongsheng@627: msgid "" dongsheng@627: "Not only does Mercurial give you a variety of ways to specify files; it lets " dongsheng@627: "you further winnow those files using <emphasis>filters</emphasis>. Commands " dongsheng@627: "that work with file names accept two filtering options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:241 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-opt-global\">-I</option>, or <option role=\"hg-opt-global" dongsheng@627: "\">--include</option>, lets you specify a pattern that file names must match " dongsheng@627: "in order to be processed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:246 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-opt-global\">-X</option>, or <option role=\"hg-opt-global" dongsheng@627: "\">--exclude</option>, gives you a way to <emphasis>avoid</emphasis> " dongsheng@627: "processing files, if they match this pattern." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:251 dongsheng@627: msgid "" dongsheng@627: "You can provide multiple <option role=\"hg-opt-global\">-I</option> and " dongsheng@627: "<option role=\"hg-opt-global\">-X</option> options on the command line, and " dongsheng@627: "intermix them as you please. Mercurial interprets the patterns you provide " dongsheng@627: "using glob syntax by default (but you can use regexps if you need to)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:258 dongsheng@627: msgid "" dongsheng@627: "You can read a <option role=\"hg-opt-global\">-I</option> filter as " dongsheng@627: "<quote>process only the files that match this filter</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:264 dongsheng@627: msgid "" dongsheng@627: "The <option role=\"hg-opt-global\">-X</option> filter is best read as " dongsheng@627: "<quote>process only the files that don't match this pattern</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:272 dongsheng@627: msgid "Ignoring unwanted files and directories" dongsheng@630: msgstr "忽略不需要的文件和目录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:274 dongsheng@627: msgid "XXX." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:278 dongsheng@627: msgid "Case sensitivity" dongsheng@630: msgstr "大小写敏感性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:280 dongsheng@627: msgid "" dongsheng@627: "If you're working in a mixed development environment that contains both Linux " dongsheng@627: "(or other Unix) systems and Macs or Windows systems, you should keep in the " dongsheng@627: "back of your mind the knowledge that they treat the case (<quote>N</quote> " dongsheng@627: "versus <quote>n</quote>) of file names in incompatible ways. This is not " dongsheng@627: "very likely to affect you, and it's easy to deal with if it does, but it " dongsheng@627: "could surprise you if you don't know about it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:289 dongsheng@627: msgid "" dongsheng@627: "Operating systems and filesystems differ in the way they handle the " dongsheng@627: "<emphasis>case</emphasis> of characters in file and directory names. There " dongsheng@627: "are three common ways to handle case in names." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:294 dongsheng@627: msgid "" dongsheng@627: "Completely case insensitive. Uppercase and lowercase versions of a letter " dongsheng@627: "are treated as identical, both when creating a file and during subsequent " dongsheng@627: "accesses. This is common on older DOS-based systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:299 dongsheng@627: msgid "" dongsheng@627: "Case preserving, but insensitive. When a file or directory is created, the " dongsheng@627: "case of its name is stored, and can be retrieved and displayed by the " dongsheng@627: "operating system. When an existing file is being looked up, its case is " dongsheng@627: "ignored. This is the standard arrangement on Windows and MacOS. The names " dongsheng@627: "<filename>foo</filename> and <filename>FoO</filename> identify the same " dongsheng@627: "file. This treatment of uppercase and lowercase letters as interchangeable " dongsheng@627: "is also referred to as <emphasis>case folding</emphasis>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:310 dongsheng@627: msgid "" dongsheng@627: "Case sensitive. The case of a name is significant at all times. The names " dongsheng@627: "<filename>foo</filename> and {FoO} identify different files. This is the way " dongsheng@627: "Linux and Unix systems normally work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:316 dongsheng@627: msgid "" dongsheng@627: "On Unix-like systems, it is possible to have any or all of the above ways of " dongsheng@627: "handling case in action at once. For example, if you use a USB thumb drive " dongsheng@627: "formatted with a FAT32 filesystem on a Linux system, Linux will handle names " dongsheng@627: "on that filesystem in a case preserving, but insensitive, way." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:323 dongsheng@627: msgid "Safe, portable repository storage" dongsheng@630: msgstr "安全，可移植的版本库存储" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:325 dongsheng@627: msgid "" dongsheng@627: "Mercurial's repository storage mechanism is <emphasis>case safe</emphasis>. " dongsheng@627: "It translates file names so that they can be safely stored on both case " dongsheng@627: "sensitive and case insensitive filesystems. This means that you can use " dongsheng@627: "normal file copying tools to transfer a Mercurial repository onto, for " dongsheng@627: "example, a USB thumb drive, and safely move that drive and repository back " dongsheng@627: "and forth between a Mac, a PC running Windows, and a Linux box." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:336 dongsheng@627: msgid "Detecting case conflicts" dongsheng@630: msgstr "检测大小写冲突" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:338 dongsheng@627: msgid "" dongsheng@627: "When operating in the working directory, Mercurial honours the naming policy " dongsheng@627: "of the filesystem where the working directory is located. If the filesystem " dongsheng@627: "is case preserving, but insensitive, Mercurial will treat names that differ " dongsheng@627: "only in case as the same." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:344 dongsheng@627: msgid "" dongsheng@627: "An important aspect of this approach is that it is possible to commit a " dongsheng@627: "changeset on a case sensitive (typically Linux or Unix) filesystem that will " dongsheng@627: "cause trouble for users on case insensitive (usually Windows and MacOS) " dongsheng@627: "users. If a Linux user commits changes to two files, one named " dongsheng@627: "<filename>myfile.c</filename> and the other named <filename>MyFile.C</" dongsheng@627: "filename>, they will be stored correctly in the repository. And in the " dongsheng@627: "working directories of other Linux users, they will be correctly represented " dongsheng@627: "as separate files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:355 dongsheng@627: msgid "" dongsheng@627: "If a Windows or Mac user pulls this change, they will not initially have a " dongsheng@627: "problem, because Mercurial's repository storage mechanism is case safe. " dongsheng@627: "However, once they try to <command role=\"hg-cmd\">hg update</command> the " dongsheng@627: "working directory to that changeset, or <command role=\"hg-cmd\">hg merge</" dongsheng@627: "command> with that changeset, Mercurial will spot the conflict between the " dongsheng@627: "two file names that the filesystem would treat as the same, and forbid the " dongsheng@627: "update or merge from occurring." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:367 dongsheng@627: msgid "Fixing a case conflict" dongsheng@630: msgstr "修正大小写冲突" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:369 dongsheng@627: msgid "" dongsheng@627: "If you are using Windows or a Mac in a mixed environment where some of your " dongsheng@627: "collaborators are using Linux or Unix, and Mercurial reports a case folding " dongsheng@627: "conflict when you try to <command role=\"hg-cmd\">hg update</command> or " dongsheng@627: "<command role=\"hg-cmd\">hg merge</command>, the procedure to fix the problem " dongsheng@627: "is simple." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:376 dongsheng@627: msgid "" dongsheng@627: "Just find a nearby Linux or Unix box, clone the problem repository onto it, " dongsheng@627: "and use Mercurial's <command role=\"hg-cmd\">hg rename</command> command to " dongsheng@627: "change the names of any offending files or directories so that they will no " dongsheng@627: "longer cause case folding conflicts. Commit this change, <command role=\"hg-" dongsheng@627: "cmd\">hg pull</command> or <command role=\"hg-cmd\">hg push</command> it " dongsheng@627: "across to your Windows or MacOS system, and <command role=\"hg-cmd\">hg " dongsheng@627: "update</command> to the revision with the non-conflicting names." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:386 dongsheng@627: msgid "" dongsheng@627: "The changeset with case-conflicting names will remain in your project's " dongsheng@627: "history, and you still won't be able to <command role=\"hg-cmd\">hg update</" dongsheng@627: "command> your working directory to that changeset on a Windows or MacOS " dongsheng@627: "system, but you can continue development unimpeded." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch07-filenames.xml:393 dongsheng@627: msgid "" dongsheng@627: "Prior to version 0.9.3, Mercurial did not use a case safe repository storage " dongsheng@627: "mechanism, and did not detect case folding conflicts. If you are using an " dongsheng@627: "older version of Mercurial on Windows or MacOS, I strongly recommend that you " dongsheng@627: "upgrade." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch08-branch.xml:5 dongsheng@627: msgid "Managing releases and branchy development" dongsheng@627: msgstr "发布管理与分支开发" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch08-branch.xml:7 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides several mechanisms for you to manage a project that is " dongsheng@627: "making progress on multiple fronts at once. To understand these mechanisms, " dongsheng@627: "let's first take a brief look at a fairly normal software project structure." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch08-branch.xml:12 dongsheng@627: msgid "" dongsheng@627: "Many software projects issue periodic <quote>major</quote> releases that " dongsheng@627: "contain substantial new features. In parallel, they may issue <quote>minor</" dongsheng@627: "quote> releases. These are usually identical to the major releases off which " dongsheng@627: "they're based, but with a few bugs fixed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch08-branch.xml:18 dongsheng@627: msgid "" dongsheng@627: "In this chapter, we'll start by talking about how to keep records of project " dongsheng@627: "milestones such as releases. We'll then continue on to talk about the flow " dongsheng@627: "of work between different phases of a project, and how Mercurial can help you " dongsheng@627: "to isolate and manage this work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:25 dongsheng@627: msgid "Giving a persistent name to a revision" dongsheng@635: msgstr "给版本指定一个永久的名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:27 dongsheng@627: msgid "" dongsheng@627: "Once you decide that you'd like to call a particular revision a " dongsheng@627: "<quote>release</quote>, it's a good idea to record the identity of that " dongsheng@627: "revision. This will let you reproduce that release at a later date, for " dongsheng@627: "whatever purpose you might need at the time (reproducing a bug, porting to a " dongsheng@627: "new platform, etc). &interaction.tag.init;" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:34 dongsheng@627: msgid "" dongsheng@627: "Mercurial lets you give a permanent name to any revision using the <command " dongsheng@627: "role=\"hg-cmd\">hg tag</command> command. Not surprisingly, these names are " dongsheng@627: "called <quote>tags</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:40 dongsheng@627: msgid "" dongsheng@627: "A tag is nothing more than a <quote>symbolic name</quote> for a revision. " dongsheng@627: "Tags exist purely for your convenience, so that you have a handy permanent " dongsheng@627: "way to refer to a revision; Mercurial doesn't interpret the tag names you use " dongsheng@627: "in any way. Neither does Mercurial place any restrictions on the name of a " dongsheng@627: "tag, beyond a few that are necessary to ensure that a tag can be parsed " dongsheng@627: "unambiguously. A tag name cannot contain any of the following characters:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:49 dongsheng@627: msgid "Colon (ASCII 58, <quote><literal>:</literal></quote>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:52 dongsheng@627: msgid "Carriage return (ASCII 13, <quote><literal>\\r</literal></quote>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:55 dongsheng@627: msgid "Newline (ASCII 10, <quote><literal>\\n</literal></quote>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:59 dongsheng@627: msgid "" dongsheng@627: "You can use the <command role=\"hg-cmd\">hg tags</command> command to display " dongsheng@627: "the tags present in your repository. In the output, each tagged revision is " dongsheng@627: "identified first by its name, then by revision number, and finally by the " dongsheng@627: "unique hash of the revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:67 dongsheng@627: msgid "" dongsheng@627: "Notice that <literal>tip</literal> is listed in the output of <command role=" dongsheng@627: "\"hg-cmd\">hg tags</command>. The <literal>tip</literal> tag is a special " dongsheng@627: "<quote>floating</quote> tag, which always identifies the newest revision in " dongsheng@627: "the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:73 dongsheng@627: msgid "" dongsheng@627: "In the output of the <command role=\"hg-cmd\">hg tags</command> command, tags " dongsheng@627: "are listed in reverse order, by revision number. This usually means that " dongsheng@627: "recent tags are listed before older tags. It also means that <literal>tip</" dongsheng@627: "literal> is always going to be the first tag listed in the output of <command " dongsheng@627: "role=\"hg-cmd\">hg tags</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:80 dongsheng@627: msgid "" dongsheng@627: "When you run <command role=\"hg-cmd\">hg log</command>, if it displays a " dongsheng@627: "revision that has tags associated with it, it will print those tags." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:86 dongsheng@627: msgid "" dongsheng@627: "Any time you need to provide a revision ID to a Mercurial command, the " dongsheng@627: "command will accept a tag name in its place. Internally, Mercurial will " dongsheng@627: "translate your tag name into the corresponding revision ID, then use that." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:93 dongsheng@627: msgid "" dongsheng@627: "There's no limit on the number of tags you can have in a repository, or on " dongsheng@627: "the number of tags that a single revision can have. As a practical matter, " dongsheng@627: "it's not a great idea to have <quote>too many</quote> (a number which will " dongsheng@627: "vary from project to project), simply because tags are supposed to help you " dongsheng@627: "to find revisions. If you have lots of tags, the ease of using them to " dongsheng@627: "identify revisions diminishes rapidly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:101 dongsheng@627: msgid "" dongsheng@627: "For example, if your project has milestones as frequent as every few days, " dongsheng@627: "it's perfectly reasonable to tag each one of those. But if you have a " dongsheng@627: "continuous build system that makes sure every revision can be built cleanly, " dongsheng@627: "you'd be introducing a lot of noise if you were to tag every clean build. " dongsheng@627: "Instead, you could tag failed builds (on the assumption that they're rare!), " dongsheng@627: "or simply not use tags to track buildability." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:109 dongsheng@627: msgid "" dongsheng@627: "If you want to remove a tag that you no longer want, use <command role=\"hg-" dongsheng@627: "cmd\">hg tag --remove</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:114 dongsheng@627: msgid "" dongsheng@627: "You can also modify a tag at any time, so that it identifies a different " dongsheng@627: "revision, by simply issuing a new <command role=\"hg-cmd\">hg tag</command> " dongsheng@627: "command. You'll have to use the <option role=\"hg-opt-tag\">-f</option> " dongsheng@627: "option to tell Mercurial that you <emphasis>really</emphasis> want to update " dongsheng@627: "the tag." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:123 dongsheng@627: msgid "" dongsheng@627: "There will still be a permanent record of the previous identity of the tag, " dongsheng@627: "but Mercurial will no longer use it. There's thus no penalty to tagging the " dongsheng@627: "wrong revision; all you have to do is turn around and tag the correct " dongsheng@627: "revision once you discover your error." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:129 dongsheng@627: msgid "" dongsheng@627: "Mercurial stores tags in a normal revision-controlled file in your " dongsheng@627: "repository. If you've created any tags, you'll find them in a file named " dongsheng@627: "<filename role=\"special\">.hgtags</filename>. When you run the <command " dongsheng@627: "role=\"hg-cmd\">hg tag</command> command, Mercurial modifies this file, then " dongsheng@627: "automatically commits the change to it. This means that every time you run " dongsheng@627: "<command role=\"hg-cmd\">hg tag</command>, you'll see a corresponding " dongsheng@627: "changeset in the output of <command role=\"hg-cmd\">hg log</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch08-branch.xml:142 dongsheng@627: msgid "Handling tag conflicts during a merge" dongsheng@635: msgstr "在合并期间处理标签冲突" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:144 dongsheng@627: msgid "" dongsheng@627: "You won't often need to care about the <filename role=\"special\">.hgtags</" dongsheng@627: "filename> file, but it sometimes makes its presence known during a merge. " dongsheng@627: "The format of the file is simple: it consists of a series of lines. Each " dongsheng@627: "line starts with a changeset hash, followed by a space, followed by the name " dongsheng@627: "of a tag." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:151 dongsheng@627: msgid "" dongsheng@627: "If you're resolving a conflict in the <filename role=\"special\">.hgtags</" dongsheng@627: "filename> file during a merge, there's one twist to modifying the <filename " dongsheng@627: "role=\"special\">.hgtags</filename> file: when Mercurial is parsing the tags " dongsheng@627: "in a repository, it <emphasis>never</emphasis> reads the working copy of the " dongsheng@627: "<filename role=\"special\">.hgtags</filename> file. Instead, it reads the " dongsheng@627: "<emphasis>most recently committed</emphasis> revision of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:161 dongsheng@627: msgid "" dongsheng@627: "An unfortunate consequence of this design is that you can't actually verify " dongsheng@627: "that your merged <filename role=\"special\">.hgtags</filename> file is " dongsheng@627: "correct until <emphasis>after</emphasis> you've committed a change. So if " dongsheng@627: "you find yourself resolving a conflict on <filename role=\"special\">.hgtags</" dongsheng@627: "filename> during a merge, be sure to run <command role=\"hg-cmd\">hg tags</" dongsheng@627: "command> after you commit. If it finds an error in the <filename role=" dongsheng@627: "\"special\">.hgtags</filename> file, it will report the location of the " dongsheng@627: "error, which you can then fix and commit. You should then run <command role=" dongsheng@627: "\"hg-cmd\">hg tags</command> again, just to be sure that your fix is correct." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch08-branch.xml:176 dongsheng@627: msgid "Tags and cloning" dongsheng@635: msgstr "标签与克隆" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:178 dongsheng@627: msgid "" dongsheng@627: "You may have noticed that the <command role=\"hg-cmd\">hg clone</command> " dongsheng@627: "command has a <option role=\"hg-opt-clone\">-r</option> option that lets you " dongsheng@627: "clone an exact copy of the repository as of a particular changeset. The new " dongsheng@627: "clone will not contain any project history that comes after the revision you " dongsheng@627: "specified. This has an interaction with tags that can surprise the unwary." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:186 dongsheng@627: msgid "" dongsheng@627: "Recall that a tag is stored as a revision to the <filename role=\"special\">." dongsheng@627: "hgtags</filename> file, so that when you create a tag, the changeset in which " dongsheng@627: "it's recorded necessarily refers to an older changeset. When you run " dongsheng@627: "<command role=\"hg-cmd\">hg clone -r foo</command> to clone a repository as " dongsheng@627: "of tag <literal>foo</literal>, the new clone <emphasis>will not contain the " dongsheng@627: "history that created the tag</emphasis> that you used to clone the " dongsheng@627: "repository. The result is that you'll get exactly the right subset of the " dongsheng@627: "project's history in the new repository, but <emphasis>not</emphasis> the tag " dongsheng@627: "you might have expected." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch08-branch.xml:201 dongsheng@627: msgid "When permanent tags are too much" dongsheng@635: msgstr "当永久标签太多的时候" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:203 dongsheng@627: msgid "" dongsheng@627: "Since Mercurial's tags are revision controlled and carried around with a " dongsheng@627: "project's history, everyone you work with will see the tags you create. But " dongsheng@627: "giving names to revisions has uses beyond simply noting that revision " dongsheng@627: "<literal>4237e45506ee</literal> is really <literal>v2.0.2</literal>. If " dongsheng@627: "you're trying to track down a subtle bug, you might want a tag to remind you " dongsheng@627: "of something like <quote>Anne saw the symptoms with this revision</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:213 dongsheng@627: msgid "" dongsheng@627: "For cases like this, what you might want to use are <emphasis>local</" dongsheng@627: "emphasis> tags. You can create a local tag with the <option role=\"hg-opt-tag" dongsheng@627: "\">-l</option> option to the <command role=\"hg-cmd\">hg tag</command> " dongsheng@627: "command. This will store the tag in a file called <filename role=\"special" dongsheng@627: "\">.hg/localtags</filename>. Unlike <filename role=\"special\">.hgtags</" dongsheng@627: "filename>, <filename role=\"special\">.hg/localtags</filename> is not " dongsheng@627: "revision controlled. Any tags you create using <option role=\"hg-opt-tag\">-" dongsheng@627: "l</option> remain strictly local to the repository you're currently working " dongsheng@627: "in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:228 dongsheng@627: msgid "The flow of changes&emdash;big picture vs. little" dongsheng@635: msgstr "修改流程&emdash;宏观与微观" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:230 dongsheng@627: msgid "" dongsheng@627: "To return to the outline I sketched at the beginning of a chapter, let's " dongsheng@627: "think about a project that has multiple concurrent pieces of work under " dongsheng@627: "development at once." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:234 dongsheng@627: msgid "" dongsheng@627: "There might be a push for a new <quote>main</quote> release; a new minor " dongsheng@627: "bugfix release to the last main release; and an unexpected <quote>hot fix</" dongsheng@627: "quote> to an old release that is now in maintenance mode." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:239 dongsheng@627: msgid "" dongsheng@627: "The usual way people refer to these different concurrent directions of " dongsheng@627: "development is as <quote>branches</quote>. However, we've already seen " dongsheng@627: "numerous times that Mercurial treats <emphasis>all of history</emphasis> as a " dongsheng@627: "series of branches and merges. Really, what we have here is two ideas that " dongsheng@627: "are peripherally related, but which happen to share a name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:246 dongsheng@627: msgid "" dongsheng@627: "<quote>Big picture</quote> branches represent the sweep of a project's " dongsheng@627: "evolution; people give them names, and talk about them in conversation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:250 dongsheng@627: msgid "" dongsheng@627: "<quote>Little picture</quote> branches are artefacts of the day-to-day " dongsheng@627: "activity of developing and merging changes. They expose the narrative of how " dongsheng@627: "the code was developed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:258 dongsheng@627: msgid "Managing big-picture branches in repositories" dongsheng@635: msgstr "在版本库中管理分支" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:260 dongsheng@627: msgid "" dongsheng@627: "The easiest way to isolate a <quote>big picture</quote> branch in Mercurial " dongsheng@627: "is in a dedicated repository. If you have an existing shared " dongsheng@627: "repository&emdash;let's call it <literal>myproject</literal>&emdash;that " dongsheng@627: "reaches a <quote>1.0</quote> milestone, you can start to prepare for future " dongsheng@627: "maintenance releases on top of version 1.0 by tagging the revision from which " dongsheng@627: "you prepared the 1.0 release." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:270 dongsheng@627: msgid "" dongsheng@627: "You can then clone a new shared <literal>myproject-1.0.1</literal> repository " dongsheng@627: "as of that tag." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:276 dongsheng@627: msgid "" dongsheng@627: "Afterwards, if someone needs to work on a bug fix that ought to go into an " dongsheng@627: "upcoming 1.0.1 minor release, they clone the <literal>myproject-1.0.1</" dongsheng@627: "literal> repository, make their changes, and push them back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:283 dongsheng@627: msgid "" dongsheng@627: "Meanwhile, development for the next major release can continue, isolated and " dongsheng@627: "unabated, in the <literal>myproject</literal> repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:291 dongsheng@627: msgid "Don't repeat yourself: merging across branches" dongsheng@635: msgstr "不要重复劳动：在分支间合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:293 dongsheng@627: msgid "" dongsheng@627: "In many cases, if you have a bug to fix on a maintenance branch, the chances " dongsheng@627: "are good that the bug exists on your project's main branch (and possibly " dongsheng@627: "other maintenance branches, too). It's a rare developer who wants to fix the " dongsheng@627: "same bug multiple times, so let's look at a few ways that Mercurial can help " dongsheng@627: "you to manage these bugfixes without duplicating your work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:301 dongsheng@627: msgid "" dongsheng@627: "In the simplest instance, all you need to do is pull changes from your " dongsheng@627: "maintenance branch into your local clone of the target branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:307 dongsheng@627: msgid "" dongsheng@627: "You'll then need to merge the heads of the two branches, and push back to the " dongsheng@627: "main branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:314 dongsheng@627: msgid "Naming branches within one repository" dongsheng@635: msgstr "版本库中的命名分支" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:316 dongsheng@627: msgid "" dongsheng@627: "In most instances, isolating branches in repositories is the right approach. " dongsheng@627: "Its simplicity makes it easy to understand; and so it's hard to make " dongsheng@627: "mistakes. There's a one-to-one relationship between branches you're working " dongsheng@627: "in and directories on your system. This lets you use normal (non-Mercurial-" dongsheng@627: "aware) tools to work on files within a branch/repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:323 dongsheng@627: msgid "" dongsheng@627: "If you're more in the <quote>power user</quote> category (<emphasis>and</" dongsheng@627: "emphasis> your collaborators are too), there is an alternative way of " dongsheng@627: "handling branches that you can consider. I've already mentioned the human-" dongsheng@627: "level distinction between <quote>small picture</quote> and <quote>big " dongsheng@627: "picture</quote> branches. While Mercurial works with multiple <quote>small " dongsheng@627: "picture</quote> branches in a repository all the time (for example after you " dongsheng@627: "pull changes in, but before you merge them), it can <emphasis>also</emphasis> " dongsheng@627: "work with multiple <quote>big picture</quote> branches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:334 dongsheng@627: msgid "" dongsheng@627: "The key to working this way is that Mercurial lets you assign a persistent " dongsheng@627: "<emphasis>name</emphasis> to a branch. There always exists a branch named " dongsheng@627: "<literal>default</literal>. Even before you start naming branches yourself, " dongsheng@627: "you can find traces of the <literal>default</literal> branch if you look for " dongsheng@627: "them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:341 dongsheng@627: msgid "" dongsheng@627: "As an example, when you run the <command role=\"hg-cmd\">hg commit</command> " dongsheng@627: "command, and it pops up your editor so that you can enter a commit message, " dongsheng@627: "look for a line that contains the text <quote><literal>HG: branch default</" dongsheng@627: "literal></quote> at the bottom. This is telling you that your commit will " dongsheng@627: "occur on the branch named <literal>default</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:348 dongsheng@627: msgid "" dongsheng@627: "To start working with named branches, use the <command role=\"hg-cmd\">hg " dongsheng@627: "branches</command> command. This command lists the named branches already " dongsheng@627: "present in your repository, telling you which changeset is the tip of each." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:355 dongsheng@627: msgid "" dongsheng@627: "Since you haven't created any named branches yet, the only one that exists is " dongsheng@627: "<literal>default</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:358 dongsheng@627: msgid "" dongsheng@627: "To find out what the <quote>current</quote> branch is, run the <command role=" dongsheng@627: "\"hg-cmd\">hg branch</command> command, giving it no arguments. This tells " dongsheng@627: "you what branch the parent of the current changeset is on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:365 dongsheng@627: msgid "" dongsheng@627: "To create a new branch, run the <command role=\"hg-cmd\">hg branch</command> " dongsheng@627: "command again. This time, give it one argument: the name of the branch you " dongsheng@627: "want to create." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:371 dongsheng@627: msgid "" dongsheng@627: "After you've created a branch, you might wonder what effect the <command role=" dongsheng@627: "\"hg-cmd\">hg branch</command> command has had. What do the <command role=" dongsheng@627: "\"hg-cmd\">hg status</command> and <command role=\"hg-cmd\">hg tip</command> " dongsheng@627: "commands report?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:378 dongsheng@627: msgid "" dongsheng@627: "Nothing has changed in the working directory, and there's been no new history " dongsheng@627: "created. As this suggests, running the <command role=\"hg-cmd\">hg branch</" dongsheng@627: "command> command has no permanent effect; it only tells Mercurial what branch " dongsheng@627: "name to use the <emphasis>next</emphasis> time you commit a changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:385 dongsheng@627: msgid "" dongsheng@627: "When you commit a change, Mercurial records the name of the branch on which " dongsheng@627: "you committed. Once you've switched from the <literal>default</literal> " dongsheng@627: "branch to another and committed, you'll see the name of the new branch show " dongsheng@627: "up in the output of <command role=\"hg-cmd\">hg log</command>, <command role=" dongsheng@627: "\"hg-cmd\">hg tip</command>, and other commands that display the same kind of " dongsheng@627: "output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:395 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg log</command>-like commands will print the " dongsheng@627: "branch name of every changeset that's not on the <literal>default</literal> " dongsheng@627: "branch. As a result, if you never use named branches, you'll never see this " dongsheng@627: "information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:400 dongsheng@627: msgid "" dongsheng@627: "Once you've named a branch and committed a change with that name, every " dongsheng@627: "subsequent commit that descends from that change will inherit the same branch " dongsheng@627: "name. You can change the name of a branch at any time, using the <command " dongsheng@627: "role=\"hg-cmd\">hg branch</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:408 dongsheng@627: msgid "" dongsheng@627: "In practice, this is something you won't do very often, as branch names tend " dongsheng@627: "to have fairly long lifetimes. (This isn't a rule, just an observation.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:414 dongsheng@627: msgid "Dealing with multiple named branches in a repository" dongsheng@635: msgstr "在版本库中处理多个命名分支" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:417 dongsheng@627: msgid "" dongsheng@627: "If you have more than one named branch in a repository, Mercurial will " dongsheng@627: "remember the branch that your working directory on when you start a command " dongsheng@627: "like <command role=\"hg-cmd\">hg update</command> or <command role=\"hg-cmd" dongsheng@627: "\">hg pull -u</command>. It will update the working directory to the tip of " dongsheng@627: "this branch, no matter what the <quote>repo-wide</quote> tip is. To update " dongsheng@627: "to a revision that's on a different named branch, you may need to use the " dongsheng@627: "<option role=\"hg-opt-update\">-C</option> option to <command role=\"hg-cmd" dongsheng@627: "\">hg update</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:427 dongsheng@627: msgid "" dongsheng@627: "This behaviour is a little subtle, so let's see it in action. First, let's " dongsheng@627: "remind ourselves what branch we're currently on, and what branches are in our " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:433 dongsheng@627: msgid "" dongsheng@627: "We're on the <literal>bar</literal> branch, but there also exists an older " dongsheng@627: "<command role=\"hg-cmd\">hg foo</command> branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:437 dongsheng@627: msgid "" dongsheng@627: "We can <command role=\"hg-cmd\">hg update</command> back and forth between " dongsheng@627: "the tips of the <literal>foo</literal> and <literal>bar</literal> branches " dongsheng@627: "without needing to use the <option role=\"hg-opt-update\">-C</option> option, " dongsheng@627: "because this only involves going backwards and forwards linearly through our " dongsheng@627: "change history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:446 dongsheng@627: msgid "" dongsheng@627: "If we go back to the <literal>foo</literal> branch and then run <command role=" dongsheng@627: "\"hg-cmd\">hg update</command>, it will keep us on <literal>foo</literal>, " dongsheng@627: "not move us to the tip of <literal>bar</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:453 dongsheng@627: msgid "" dongsheng@627: "Committing a new change on the <literal>foo</literal> branch introduces a new " dongsheng@627: "head." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:460 dongsheng@627: msgid "Branch names and merging" dongsheng@635: msgstr "分支名称与合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:462 dongsheng@627: msgid "" dongsheng@627: "As you've probably noticed, merges in Mercurial are not symmetrical. Let's " dongsheng@627: "say our repository has two heads, 17 and 23. If I <command role=\"hg-cmd" dongsheng@627: "\">hg update</command> to 17 and then <command role=\"hg-cmd\">hg merge</" dongsheng@627: "command> with 23, Mercurial records 17 as the first parent of the merge, and " dongsheng@627: "23 as the second. Whereas if I <command role=\"hg-cmd\">hg update</command> " dongsheng@627: "to 23 and then <command role=\"hg-cmd\">hg merge</command> with 17, it " dongsheng@627: "records 23 as the first parent, and 17 as the second." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:472 dongsheng@627: msgid "" dongsheng@627: "This affects Mercurial's choice of branch name when you merge. After a " dongsheng@627: "merge, Mercurial will retain the branch name of the first parent when you " dongsheng@627: "commit the result of the merge. If your first parent's branch name is " dongsheng@627: "<literal>foo</literal>, and you merge with <literal>bar</literal>, the branch " dongsheng@627: "name will still be <literal>foo</literal> after you merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:479 dongsheng@627: msgid "" dongsheng@627: "It's not unusual for a repository to contain multiple heads, each with the " dongsheng@627: "same branch name. Let's say I'm working on the <literal>foo</literal> " dongsheng@627: "branch, and so are you. We commit different changes; I pull your changes; I " dongsheng@627: "now have two heads, each claiming to be on the <literal>foo</literal> " dongsheng@627: "branch. The result of a merge will be a single head on the <literal>foo</" dongsheng@627: "literal> branch, as you might hope." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:487 dongsheng@627: msgid "" dongsheng@627: "But if I'm working on the <literal>bar</literal> branch, and I merge work " dongsheng@627: "from the <literal>foo</literal> branch, the result will remain on the " dongsheng@627: "<literal>bar</literal> branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:493 dongsheng@627: msgid "" dongsheng@627: "To give a more concrete example, if I'm working on the <literal>bleeding-" dongsheng@627: "edge</literal> branch, and I want to bring in the latest fixes from the " dongsheng@627: "<literal>stable</literal> branch, Mercurial will choose the <quote>right</" dongsheng@627: "quote> (<literal>bleeding-edge</literal>) branch name when I pull and merge " dongsheng@627: "from <literal>stable</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:502 dongsheng@627: msgid "Branch naming is generally useful" dongsheng@635: msgstr "分支名称通常都很有用" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:504 dongsheng@627: msgid "" dongsheng@627: "You shouldn't think of named branches as applicable only to situations where " dongsheng@627: "you have multiple long-lived branches cohabiting in a single repository. " dongsheng@627: "They're very useful even in the one-branch-per-repository case." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:509 dongsheng@627: msgid "" dongsheng@627: "In the simplest case, giving a name to each branch gives you a permanent " dongsheng@627: "record of which branch a changeset originated on. This gives you more " dongsheng@627: "context when you're trying to follow the history of a long-lived branchy " dongsheng@627: "project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:514 dongsheng@627: msgid "" dongsheng@627: "If you're working with shared repositories, you can set up a <literal role=" dongsheng@627: "\"hook\">pretxnchangegroup</literal> hook on each that will block incoming " dongsheng@627: "changes that have the <quote>wrong</quote> branch name. This provides a " dongsheng@627: "simple, but effective, defence against people accidentally pushing changes " dongsheng@627: "from a <quote>bleeding edge</quote> branch to a <quote>stable</quote> " dongsheng@627: "branch. Such a hook might look like this inside the shared repo's <filename " dongsheng@627: "role=\"special\"> /.hgrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch09-undo.xml:5 dongsheng@627: msgid "Finding and fixing mistakes" dongsheng@627: msgstr "查找和修改错误" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch09-undo.xml:7 dongsheng@627: msgid "" dongsheng@627: "To err might be human, but to really handle the consequences well takes a top-" dongsheng@627: "notch revision control system. In this chapter, we'll discuss some of the " dongsheng@627: "techniques you can use when you find that a problem has crept into your " dongsheng@627: "project. Mercurial has some highly capable features that will help you to " dongsheng@627: "isolate the sources of problems, and to handle them appropriately." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:15 dongsheng@627: msgid "Erasing local history" dongsheng@635: msgstr "销毁本地历史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:18 dongsheng@627: msgid "The accidental commit" dongsheng@635: msgstr "意外的提交" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:20 dongsheng@627: msgid "" dongsheng@627: "I have the occasional but persistent problem of typing rather more quickly " dongsheng@627: "than I can think, which sometimes results in me committing a changeset that " dongsheng@627: "is either incomplete or plain wrong. In my case, the usual kind of " dongsheng@627: "incomplete changeset is one in which I've created a new source file, but " dongsheng@627: "forgotten to <command role=\"hg-cmd\">hg add</command> it. A <quote>plain " dongsheng@627: "wrong</quote> changeset is not as common, but no less annoying." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:31 dongsheng@627: msgid "Rolling back a transaction" dongsheng@635: msgstr "回滚一个事务" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:33 dongsheng@627: msgid "" dongsheng@627: "In section <xref linkend=\"sec.concepts.txn\"/>, I mentioned that Mercurial " dongsheng@627: "treats each modification of a repository as a <emphasis>transaction</" dongsheng@627: "emphasis>. Every time you commit a changeset or pull changes from another " dongsheng@627: "repository, Mercurial remembers what you did. You can undo, or " dongsheng@627: "<emphasis>roll back</emphasis>, exactly one of these actions using the " dongsheng@627: "<command role=\"hg-cmd\">hg rollback</command> command. (See section <xref " dongsheng@627: "linkend=\"sec.undo.rollback-after-push\"/> for an important caveat about the " dongsheng@627: "use of this command.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:43 dongsheng@627: msgid "" dongsheng@627: "Here's a mistake that I often find myself making: committing a change in " dongsheng@627: "which I've created a new file, but forgotten to <command role=\"hg-cmd\">hg " dongsheng@627: "add</command> it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:50 dongsheng@627: msgid "" dongsheng@627: "Looking at the output of <command role=\"hg-cmd\">hg status</command> after " dongsheng@627: "the commit immediately confirms the error." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:56 dongsheng@627: msgid "" dongsheng@627: "The commit captured the changes to the file <filename>a</filename>, but not " dongsheng@627: "the new file <filename>b</filename>. If I were to push this changeset to a " dongsheng@627: "repository that I shared with a colleague, the chances are high that " dongsheng@627: "something in <filename>a</filename> would refer to <filename>b</filename>, " dongsheng@627: "which would not be present in their repository when they pulled my changes. " dongsheng@627: "I would thus become the object of some indignation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:65 dongsheng@627: msgid "" dongsheng@627: "However, luck is with me&emdash;I've caught my error before I pushed the " dongsheng@627: "changeset. I use the <command role=\"hg-cmd\">hg rollback</command> command, " dongsheng@627: "and Mercurial makes that last changeset vanish." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:72 dongsheng@627: msgid "" dongsheng@627: "Notice that the changeset is no longer present in the repository's history, " dongsheng@627: "and the working directory once again thinks that the file <filename>a</" dongsheng@627: "filename> is modified. The commit and rollback have left the working " dongsheng@627: "directory exactly as it was prior to the commit; the changeset has been " dongsheng@627: "completely erased. I can now safely <command role=\"hg-cmd\">hg add</" dongsheng@627: "command> the file <filename>b</filename>, and rerun my commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:85 dongsheng@627: msgid "The erroneous pull" dongsheng@635: msgstr "错误的抓取" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:87 dongsheng@627: msgid "" dongsheng@627: "It's common practice with Mercurial to maintain separate development branches " dongsheng@627: "of a project in different repositories. Your development team might have one " dongsheng@627: "shared repository for your project's <quote>0.9</quote> release, and another, " dongsheng@627: "containing different changes, for the <quote>1.0</quote> release." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:94 dongsheng@627: msgid "" dongsheng@627: "Given this, you can imagine that the consequences could be messy if you had a " dongsheng@627: "local <quote>0.9</quote> repository, and accidentally pulled changes from the " dongsheng@627: "shared <quote>1.0</quote> repository into it. At worst, you could be paying " dongsheng@627: "insufficient attention, and push those changes into the shared <quote>0.9</" dongsheng@627: "quote> tree, confusing your entire team (but don't worry, we'll return to " dongsheng@627: "this horror scenario later). However, it's more likely that you'll notice " dongsheng@627: "immediately, because Mercurial will display the URL it's pulling from, or you " dongsheng@627: "will see it pull a suspiciously large number of changes into the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:106 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg rollback</command> command will work nicely " dongsheng@627: "to expunge all of the changesets that you just pulled. Mercurial groups all " dongsheng@627: "changes from one <command role=\"hg-cmd\">hg pull</command> into a single " dongsheng@627: "transaction, so one <command role=\"hg-cmd\">hg rollback</command> is all you " dongsheng@627: "need to undo this mistake." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:115 dongsheng@627: msgid "Rolling back is useless once you've pushed" dongsheng@635: msgstr "当完成推送后，回滚是无效的" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:117 dongsheng@627: msgid "" dongsheng@627: "The value of the <command role=\"hg-cmd\">hg rollback</command> command drops " dongsheng@627: "to zero once you've pushed your changes to another repository. Rolling back " dongsheng@627: "a change makes it disappear entirely, but <emphasis>only</emphasis> in the " dongsheng@627: "repository in which you perform the <command role=\"hg-cmd\">hg rollback</" dongsheng@627: "command>. Because a rollback eliminates history, there's no way for the " dongsheng@627: "disappearance of a change to propagate between repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:126 dongsheng@627: msgid "" dongsheng@627: "If you've pushed a change to another repository&emdash;particularly if it's a " dongsheng@627: "shared repository&emdash;it has essentially <quote>escaped into the wild,</" dongsheng@627: "quote> and you'll have to recover from your mistake in a different way. What " dongsheng@627: "will happen if you push a changeset somewhere, then roll it back, then pull " dongsheng@627: "from the repository you pushed to, is that the changeset will reappear in " dongsheng@627: "your repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:135 dongsheng@627: msgid "" dongsheng@627: "(If you absolutely know for sure that the change you want to roll back is the " dongsheng@627: "most recent change in the repository that you pushed to, <emphasis>and</" dongsheng@627: "emphasis> you know that nobody else could have pulled it from that " dongsheng@627: "repository, you can roll back the changeset there, too, but you really should " dongsheng@627: "really not rely on this working reliably. If you do this, sooner or later a " dongsheng@627: "change really will make it into a repository that you don't directly control " dongsheng@627: "(or have forgotten about), and come back to bite you.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:147 dongsheng@627: msgid "You can only roll back once" dongsheng@635: msgstr "你只能回滚一次" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:149 dongsheng@627: msgid "" dongsheng@627: "Mercurial stores exactly one transaction in its transaction log; that " dongsheng@627: "transaction is the most recent one that occurred in the repository. This " dongsheng@627: "means that you can only roll back one transaction. If you expect to be able " dongsheng@627: "to roll back one transaction, then its predecessor, this is not the behaviour " dongsheng@627: "you will get." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:158 dongsheng@627: msgid "" dongsheng@627: "Once you've rolled back one transaction in a repository, you can't roll back " dongsheng@627: "again in that repository until you perform another commit or pull." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:165 dongsheng@627: msgid "Reverting the mistaken change" dongsheng@635: msgstr "撤销错误的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:167 dongsheng@627: msgid "" dongsheng@627: "If you make a modification to a file, and decide that you really didn't want " dongsheng@627: "to change the file at all, and you haven't yet committed your changes, the " dongsheng@627: "<command role=\"hg-cmd\">hg revert</command> command is the one you'll need. " dongsheng@627: "It looks at the changeset that's the parent of the working directory, and " dongsheng@627: "restores the contents of the file to their state as of that changeset. " dongsheng@627: "(That's a long-winded way of saying that, in the normal case, it undoes your " dongsheng@627: "modifications.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:176 dongsheng@627: msgid "" dongsheng@627: "Let's illustrate how the <command role=\"hg-cmd\">hg revert</command> command " dongsheng@627: "works with yet another small example. We'll begin by modifying a file that " dongsheng@627: "Mercurial is already tracking." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:183 dongsheng@627: msgid "" dongsheng@627: "If we don't want that change, we can simply <command role=\"hg-cmd\">hg " dongsheng@627: "revert</command> the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:189 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg revert</command> command provides us with an " dongsheng@627: "extra degree of safety by saving our modified file with a <filename>.orig</" dongsheng@627: "filename> extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:196 dongsheng@627: msgid "" dongsheng@627: "Here is a summary of the cases that the <command role=\"hg-cmd\">hg revert</" dongsheng@627: "command> command can deal with. We will describe each of these in more " dongsheng@627: "detail in the section that follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:201 dongsheng@627: msgid "If you modify a file, it will restore the file to its unmodified state." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:204 dongsheng@627: msgid "" dongsheng@627: "If you <command role=\"hg-cmd\">hg add</command> a file, it will undo the " dongsheng@627: "<quote>added</quote> state of the file, but leave the file itself untouched." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:208 dongsheng@627: msgid "" dongsheng@627: "If you delete a file without telling Mercurial, it will restore the file to " dongsheng@627: "its unmodified contents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:211 dongsheng@627: msgid "" dongsheng@627: "If you use the <command role=\"hg-cmd\">hg remove</command> command to remove " dongsheng@627: "a file, it will undo the <quote>removed</quote> state of the file, and " dongsheng@627: "restore the file to its unmodified contents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:218 dongsheng@627: msgid "File management errors" dongsheng@635: msgstr "文件管理错误" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:220 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg revert</command> command is useful for more " dongsheng@627: "than just modified files. It lets you reverse the results of all of " dongsheng@627: "Mercurial's file management commands&emdash;<command role=\"hg-cmd\">hg add</" dongsheng@627: "command>, <command role=\"hg-cmd\">hg remove</command>, and so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:226 dongsheng@627: msgid "" dongsheng@627: "If you <command role=\"hg-cmd\">hg add</command> a file, then decide that in " dongsheng@627: "fact you don't want Mercurial to track it, use <command role=\"hg-cmd\">hg " dongsheng@627: "revert</command> to undo the add. Don't worry; Mercurial will not modify the " dongsheng@627: "file in any way. It will just <quote>unmark</quote> the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:234 dongsheng@627: msgid "" dongsheng@627: "Similarly, if you ask Mercurial to <command role=\"hg-cmd\">hg remove</" dongsheng@627: "command> a file, you can use <command role=\"hg-cmd\">hg revert</command> to " dongsheng@627: "restore it to the contents it had as of the parent of the working directory. " dongsheng@627: "&interaction.daily.revert.remove; This works just as well for a file that you " dongsheng@627: "deleted by hand, without telling Mercurial (recall that in Mercurial " dongsheng@627: "terminology, this kind of file is called <quote>missing</quote>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:245 dongsheng@627: msgid "" dongsheng@627: "If you revert a <command role=\"hg-cmd\">hg copy</command>, the copied-to " dongsheng@627: "file remains in your working directory afterwards, untracked. Since a copy " dongsheng@627: "doesn't affect the copied-from file in any way, Mercurial doesn't do anything " dongsheng@627: "with the copied-from file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch09-undo.xml:254 dongsheng@627: msgid "A slightly special case: reverting a rename" dongsheng@635: msgstr "一个稍微特别的案例：撤销改名" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:256 dongsheng@627: msgid "" dongsheng@627: "If you <command role=\"hg-cmd\">hg rename</command> a file, there is one " dongsheng@627: "small detail that you should remember. When you <command role=\"hg-cmd\">hg " dongsheng@627: "revert</command> a rename, it's not enough to provide the name of the renamed-" dongsheng@627: "to file, as you can see here." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:264 dongsheng@627: msgid "" dongsheng@627: "As you can see from the output of <command role=\"hg-cmd\">hg status</" dongsheng@627: "command>, the renamed-to file is no longer identified as added, but the " dongsheng@627: "renamed-<emphasis>from</emphasis> file is still removed! This is counter-" dongsheng@627: "intuitive (at least to me), but at least it's easy to deal with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:273 dongsheng@627: msgid "" dongsheng@627: "So remember, to revert a <command role=\"hg-cmd\">hg rename</command>, you " dongsheng@627: "must provide <emphasis>both</emphasis> the source and destination names." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:278 dongsheng@627: msgid "% TODO: the output doesn't look like it will be removed!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:281 dongsheng@627: msgid "" dongsheng@627: "(By the way, if you rename a file, then modify the renamed-to file, then " dongsheng@627: "revert both components of the rename, when Mercurial restores the file that " dongsheng@627: "was removed as part of the rename, it will be unmodified. If you need the " dongsheng@627: "modifications in the renamed-to file to show up in the renamed-from file, " dongsheng@627: "don't forget to copy them over.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:288 dongsheng@627: msgid "" dongsheng@627: "These fiddly aspects of reverting a rename arguably constitute a small bug in " dongsheng@627: "Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:295 dongsheng@627: msgid "Dealing with committed changes" dongsheng@635: msgstr "处理已经提交的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:297 dongsheng@627: msgid "" dongsheng@627: "Consider a case where you have committed a change $a$, and another change $b$ " dongsheng@627: "on top of it; you then realise that change $a$ was incorrect. Mercurial lets " dongsheng@627: "you <quote>back out</quote> an entire changeset automatically, and building " dongsheng@627: "blocks that let you reverse part of a changeset by hand." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:303 dongsheng@627: msgid "" dongsheng@627: "Before you read this section, here's something to keep in mind: the <command " dongsheng@627: "role=\"hg-cmd\">hg backout</command> command undoes changes by " dongsheng@627: "<emphasis>adding</emphasis> history, not by modifying or erasing it. It's " dongsheng@627: "the right tool to use if you're fixing bugs, but not if you're trying to undo " dongsheng@627: "some change that has catastrophic consequences. To deal with those, see " dongsheng@627: "section <xref linkend=\"sec.undo.aaaiiieee\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:312 dongsheng@627: msgid "Backing out a changeset" dongsheng@635: msgstr "恢复一个修改集" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:314 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg backout</command> command lets you " dongsheng@627: "<quote>undo</quote> the effects of an entire changeset in an automated " dongsheng@627: "fashion. Because Mercurial's history is immutable, this command " dongsheng@627: "<emphasis>does not</emphasis> get rid of the changeset you want to undo. " dongsheng@627: "Instead, it creates a new changeset that <emphasis>reverses</emphasis> the " dongsheng@627: "effect of the to-be-undone changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:323 dongsheng@627: msgid "" dongsheng@627: "The operation of the <command role=\"hg-cmd\">hg backout</command> command is " dongsheng@627: "a little intricate, so let's illustrate it with some examples. First, we'll " dongsheng@627: "create a repository with some simple changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:330 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg backout</command> command takes a single " dongsheng@627: "changeset ID as its argument; this is the changeset to back out. Normally, " dongsheng@627: "<command role=\"hg-cmd\">hg backout</command> will drop you into a text " dongsheng@627: "editor to write a commit message, so you can record why you're backing the " dongsheng@627: "change out. In this example, we provide a commit message on the command line " dongsheng@627: "using the <option role=\"hg-opt-backout\">-m</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:341 dongsheng@627: msgid "Backing out the tip changeset" dongsheng@635: msgstr "恢复顶点修改集" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:343 dongsheng@627: msgid "We're going to start by backing out the last changeset we committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:348 dongsheng@627: msgid "" dongsheng@627: "You can see that the second line from <filename>myfile</filename> is no " dongsheng@627: "longer present. Taking a look at the output of <command role=\"hg-cmd\">hg " dongsheng@627: "log</command> gives us an idea of what the <command role=\"hg-cmd\">hg " dongsheng@627: "backout</command> command has done. &interaction.backout.simple.log; Notice " dongsheng@627: "that the new changeset that <command role=\"hg-cmd\">hg backout</command> has " dongsheng@627: "created is a child of the changeset we backed out. It's easier to see this " dongsheng@627: "in figure <xref linkend=\"fig.undo.backout\"/>, which presents a graphical " dongsheng@627: "view of the change history. As you can see, the history is nice and linear." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch09-undo.xml:362 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/undo-simple.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch09-undo.xml:364 ../en/ch09-undo.xml:477 dongsheng@627: msgid "" dongsheng@627: "Backing out a change using the <command role=\"hg-cmd\">hg backout</command> " dongsheng@627: "command" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:373 dongsheng@627: msgid "Backing out a non-tip change" dongsheng@635: msgstr "恢复非顶点的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:375 dongsheng@627: msgid "" dongsheng@627: "If you want to back out a change other than the last one you committed, pass " dongsheng@627: "the <option role=\"hg-opt-backout\">--merge</option> option to the <command " dongsheng@627: "role=\"hg-cmd\">hg backout</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:382 dongsheng@627: msgid "" dongsheng@627: "This makes backing out any changeset a <quote>one-shot</quote> operation " dongsheng@627: "that's usually simple and fast." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:388 dongsheng@627: msgid "" dongsheng@627: "If you take a look at the contents of <filename>myfile</filename> after the " dongsheng@627: "backout finishes, you'll see that the first and third changes are present, " dongsheng@627: "but not the second." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:395 dongsheng@627: msgid "" dongsheng@627: "As the graphical history in figure <xref linkend=\"fig.undo.backout-non-tip\"/" dongsheng@627: "> illustrates, Mercurial actually commits <emphasis>two</emphasis> changes in " dongsheng@627: "this kind of situation (the box-shaped nodes are the ones that Mercurial " dongsheng@627: "commits automatically). Before Mercurial begins the backout process, it " dongsheng@627: "first remembers what the current parent of the working directory is. It then " dongsheng@627: "backs out the target changeset, and commits that as a changeset. Finally, it " dongsheng@627: "merges back to the previous parent of the working directory, and commits the " dongsheng@627: "result of the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:406 dongsheng@627: msgid "" dongsheng@627: "% TODO: to me it looks like mercurial doesn't commit the second merge " dongsheng@627: "automatically!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch09-undo.xml:410 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/undo-non-tip.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch09-undo.xml:412 dongsheng@627: msgid "" dongsheng@627: "Automated backout of a non-tip change using the <command role=\"hg-cmd\">hg " dongsheng@627: "backout</command> command" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:418 dongsheng@627: msgid "" dongsheng@627: "The result is that you end up <quote>back where you were</quote>, only with " dongsheng@627: "some extra history that undoes the effect of the changeset you wanted to back " dongsheng@627: "out." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch09-undo.xml:423 dongsheng@627: msgid "Always use the <option role=\"hg-opt-backout\">--merge</option> option" dongsheng@635: msgstr "始终使用选项 <option role=\"hg-opt-backout\">--merge</option>" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:426 dongsheng@627: msgid "" dongsheng@627: "In fact, since the <option role=\"hg-opt-backout\">--merge</option> option " dongsheng@627: "will do the <quote>right thing</quote> whether or not the changeset you're " dongsheng@627: "backing out is the tip (i.e. it won't try to merge if it's backing out the " dongsheng@627: "tip, since there's no need), you should <emphasis>always</emphasis> use this " dongsheng@627: "option when you run the <command role=\"hg-cmd\">hg backout</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:437 dongsheng@627: msgid "Gaining more control of the backout process" dongsheng@635: msgstr "在恢复处理中获得更多控制" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:439 dongsheng@627: msgid "" dongsheng@627: "While I've recommended that you always use the <option role=\"hg-opt-backout" dongsheng@627: "\">--merge</option> option when backing out a change, the <command role=\"hg-" dongsheng@627: "cmd\">hg backout</command> command lets you decide how to merge a backout " dongsheng@627: "changeset. Taking control of the backout process by hand is something you " dongsheng@627: "will rarely need to do, but it can be useful to understand what the <command " dongsheng@627: "role=\"hg-cmd\">hg backout</command> command is doing for you automatically. " dongsheng@627: "To illustrate this, let's clone our first repository, but omit the backout " dongsheng@627: "change that it contains." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:452 dongsheng@627: msgid "" dongsheng@627: "As with our earlier example, We'll commit a third changeset, then back out " dongsheng@627: "its parent, and see what happens." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:458 dongsheng@627: msgid "" dongsheng@627: "Our new changeset is again a descendant of the changeset we backout out; it's " dongsheng@627: "thus a new head, <emphasis>not</emphasis> a descendant of the changeset that " dongsheng@627: "was the tip. The <command role=\"hg-cmd\">hg backout</command> command was " dongsheng@627: "quite explicit in telling us this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:466 dongsheng@627: msgid "" dongsheng@627: "Again, it's easier to see what has happened by looking at a graph of the " dongsheng@627: "revision history, in figure <xref linkend=\"fig.undo.backout-manual\"/>. " dongsheng@627: "This makes it clear that when we use <command role=\"hg-cmd\">hg backout</" dongsheng@627: "command> to back out a change other than the tip, Mercurial adds a new head " dongsheng@627: "to the repository (the change it committed is box-shaped)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch09-undo.xml:475 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/undo-manual.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:484 dongsheng@627: msgid "" dongsheng@627: "After the <command role=\"hg-cmd\">hg backout</command> command has " dongsheng@627: "completed, it leaves the new <quote>backout</quote> changeset as the parent " dongsheng@627: "of the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:491 dongsheng@627: msgid "Now we have two isolated sets of changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:495 dongsheng@627: msgid "" dongsheng@627: "Let's think about what we expect to see as the contents of <filename>myfile</" dongsheng@627: "filename> now. The first change should be present, because we've never " dongsheng@627: "backed it out. The second change should be missing, as that's the change we " dongsheng@627: "backed out. Since the history graph shows the third change as a separate " dongsheng@627: "head, we <emphasis>don't</emphasis> expect to see the third change present in " dongsheng@627: "<filename>myfile</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:505 dongsheng@627: msgid "" dongsheng@627: "To get the third change back into the file, we just do a normal merge of our " dongsheng@627: "two heads." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:510 dongsheng@627: msgid "" dongsheng@627: "Afterwards, the graphical history of our repository looks like figure <xref " dongsheng@627: "linkend=\"fig.undo.backout-manual-merge\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch09-undo.xml:515 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/undo-manual-merge.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch09-undo.xml:517 dongsheng@627: msgid "Manually merging a backout change" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:524 dongsheng@627: msgid "Why <command role=\"hg-cmd\">hg backout</command> works as it does" dongsheng@635: msgstr "<command role=\"hg-cmd\">hg backout</command> 的内幕" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:527 dongsheng@627: msgid "" dongsheng@627: "Here's a brief description of how the <command role=\"hg-cmd\">hg backout</" dongsheng@627: "command> command works." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:530 dongsheng@627: msgid "" dongsheng@627: "It ensures that the working directory is <quote>clean</quote>, i.e. that the " dongsheng@627: "output of <command role=\"hg-cmd\">hg status</command> would be empty." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:534 dongsheng@627: msgid "" dongsheng@627: "It remembers the current parent of the working directory. Let's call this " dongsheng@627: "changeset <literal>orig</literal>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:538 dongsheng@627: msgid "" dongsheng@627: "It does the equivalent of a <command role=\"hg-cmd\">hg update</command> to " dongsheng@627: "sync the working directory to the changeset you want to back out. Let's call " dongsheng@627: "this changeset <literal>backout</literal>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:543 dongsheng@627: msgid "" dongsheng@627: "It finds the parent of that changeset. Let's call that changeset " dongsheng@627: "<literal>parent</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:546 dongsheng@627: msgid "" dongsheng@627: "For each file that the <literal>backout</literal> changeset affected, it does " dongsheng@627: "the equivalent of a <command role=\"hg-cmd\">hg revert -r parent</command> on " dongsheng@627: "that file, to restore it to the contents it had before that changeset was " dongsheng@627: "committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:553 dongsheng@627: msgid "" dongsheng@627: "It commits the result as a new changeset. This changeset has " dongsheng@627: "<literal>backout</literal> as its parent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:557 dongsheng@627: msgid "" dongsheng@627: "If you specify <option role=\"hg-opt-backout\">--merge</option> on the " dongsheng@627: "command line, it merges with <literal>orig</literal>, and commits the result " dongsheng@627: "of the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:563 dongsheng@627: msgid "" dongsheng@627: "An alternative way to implement the <command role=\"hg-cmd\">hg backout</" dongsheng@627: "command> command would be to <command role=\"hg-cmd\">hg export</command> the " dongsheng@627: "to-be-backed-out changeset as a diff, then use the <option role=\"cmd-opt-" dongsheng@627: "patch\">--reverse</option> option to the <command>patch</command> command to " dongsheng@627: "reverse the effect of the change without fiddling with the working " dongsheng@627: "directory. This sounds much simpler, but it would not work nearly as well." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:573 dongsheng@627: msgid "" dongsheng@627: "The reason that <command role=\"hg-cmd\">hg backout</command> does an update, " dongsheng@627: "a commit, a merge, and another commit is to give the merge machinery the best " dongsheng@627: "chance to do a good job when dealing with all the changes <emphasis>between</" dongsheng@627: "emphasis> the change you're backing out and the current tip." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:580 dongsheng@627: msgid "" dongsheng@627: "If you're backing out a changeset that's 100 revisions back in your project's " dongsheng@627: "history, the chances that the <command>patch</command> command will be able " dongsheng@627: "to apply a reverse diff cleanly are not good, because intervening changes are " dongsheng@627: "likely to have <quote>broken the context</quote> that <command>patch</" dongsheng@627: "command> uses to determine whether it can apply a patch (if this sounds like " dongsheng@627: "gibberish, see <xref linkend=\"sec.mq.patch\"/> for a discussion of the " dongsheng@627: "<command>patch</command> command). Also, Mercurial's merge machinery will " dongsheng@627: "handle files and directories being renamed, permission changes, and " dongsheng@627: "modifications to binary files, none of which <command>patch</command> can " dongsheng@627: "deal with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:597 dongsheng@627: msgid "Changes that should never have been" dongsheng@635: msgstr "不该发生的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:599 dongsheng@627: msgid "" dongsheng@627: "Most of the time, the <command role=\"hg-cmd\">hg backout</command> command " dongsheng@627: "is exactly what you need if you want to undo the effects of a change. It " dongsheng@627: "leaves a permanent record of exactly what you did, both when committing the " dongsheng@627: "original changeset and when you cleaned up after it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:605 dongsheng@627: msgid "" dongsheng@627: "On rare occasions, though, you may find that you've committed a change that " dongsheng@627: "really should not be present in the repository at all. For example, it would " dongsheng@627: "be very unusual, and usually considered a mistake, to commit a software " dongsheng@627: "project's object files as well as its source files. Object files have almost " dongsheng@627: "no intrinsic value, and they're <emphasis>big</emphasis>, so they increase " dongsheng@627: "the size of the repository and the amount of time it takes to clone or pull " dongsheng@627: "changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:614 dongsheng@627: msgid "" dongsheng@627: "Before I discuss the options that you have if you commit a <quote>brown paper " dongsheng@627: "bag</quote> change (the kind that's so bad that you want to pull a brown " dongsheng@627: "paper bag over your head), let me first discuss some approaches that probably " dongsheng@627: "won't work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:619 dongsheng@627: msgid "" dongsheng@627: "Since Mercurial treats history as accumulative&emdash;every change builds on " dongsheng@627: "top of all changes that preceded it&emdash;you generally can't just make " dongsheng@627: "disastrous changes disappear. The one exception is when you've just " dongsheng@627: "committed a change, and it hasn't been pushed or pulled into another " dongsheng@627: "repository. That's when you can safely use the <command role=\"hg-cmd\">hg " dongsheng@627: "rollback</command> command, as I detailed in section <xref linkend=\"sec.undo." dongsheng@627: "rollback\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:628 dongsheng@627: msgid "" dongsheng@627: "After you've pushed a bad change to another repository, you <emphasis>could</" dongsheng@627: "emphasis> still use <command role=\"hg-cmd\">hg rollback</command> to make " dongsheng@627: "your local copy of the change disappear, but it won't have the consequences " dongsheng@627: "you want. The change will still be present in the remote repository, so it " dongsheng@627: "will reappear in your local repository the next time you pull." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:636 dongsheng@627: msgid "" dongsheng@627: "If a situation like this arises, and you know which repositories your bad " dongsheng@627: "change has propagated into, you can <emphasis>try</emphasis> to get rid of " dongsheng@627: "the changeefrom <emphasis>every</emphasis> one of those repositories. This " dongsheng@627: "is, of course, not a satisfactory solution: if you miss even a single " dongsheng@627: "repository while you're expunging, the change is still <quote>in the wild</" dongsheng@627: "quote>, and could propagate further." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:644 dongsheng@627: msgid "" dongsheng@627: "If you've committed one or more changes <emphasis>after</emphasis> the change " dongsheng@627: "that you'd like to see disappear, your options are further reduced. Mercurial " dongsheng@627: "doesn't provide a way to <quote>punch a hole</quote> in history, leaving " dongsheng@627: "changesets intact." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:650 dongsheng@627: msgid "" dongsheng@627: "XXX This needs filling out. The <literal>hg-replay</literal> script in the " dongsheng@627: "<literal>examples</literal> directory works, but doesn't handle merge " dongsheng@627: "changesets. Kind of an important omission." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:656 dongsheng@627: msgid "Protect yourself from <quote>escaped</quote> changes" dongsheng@635: msgstr "使用<quote>校验</quote>修改来保护你自己" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:659 dongsheng@627: msgid "" dongsheng@627: "If you've committed some changes to your local repository and they've been " dongsheng@627: "pushed or pulled somewhere else, this isn't necessarily a disaster. You can " dongsheng@627: "protect yourself ahead of time against some classes of bad changeset. This " dongsheng@627: "is particularly easy if your team usually pulls changes from a central " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:666 dongsheng@627: msgid "" dongsheng@627: "By configuring some hooks on that repository to validate incoming changesets " dongsheng@627: "(see chapter <xref linkend=\"chap.hook\"/>), you can automatically prevent " dongsheng@627: "some kinds of bad changeset from being pushed to the central repository at " dongsheng@627: "all. With such a configuration in place, some kinds of bad changeset will " dongsheng@627: "naturally tend to <quote>die out</quote> because they can't propagate into " dongsheng@627: "the central repository. Better yet, this happens without any need for " dongsheng@627: "explicit intervention." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:676 dongsheng@627: msgid "" dongsheng@627: "For instance, an incoming change hook that verifies that a changeset will " dongsheng@627: "actually compile can prevent people from inadvertantly <quote>breaking the " dongsheng@627: "build</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:683 dongsheng@627: msgid "Finding the source of a bug" dongsheng@635: msgstr "查找问题的根源" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:685 dongsheng@627: msgid "" dongsheng@627: "While it's all very well to be able to back out a changeset that introduced a " dongsheng@627: "bug, this requires that you know which changeset to back out. Mercurial " dongsheng@627: "provides an invaluable command, called <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command>, that helps you to automate this process and accomplish it very " dongsheng@627: "efficiently." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:692 dongsheng@627: msgid "" dongsheng@627: "The idea behind the <command role=\"hg-cmd\">hg bisect</command> command is " dongsheng@627: "that a changeset has introduced some change of behaviour that you can " dongsheng@627: "identify with a simple binary test. You don't know which piece of code " dongsheng@627: "introduced the change, but you know how to test for the presence of the bug. " dongsheng@627: "The <command role=\"hg-cmd\">hg bisect</command> command uses your test to " dongsheng@627: "direct its search for the changeset that introduced the code that caused the " dongsheng@627: "bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:701 dongsheng@627: msgid "" dongsheng@627: "Here are a few scenarios to help you understand how you might apply this " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:704 dongsheng@627: msgid "" dongsheng@627: "The most recent version of your software has a bug that you remember wasn't " dongsheng@627: "present a few weeks ago, but you don't know when it was introduced. Here, " dongsheng@627: "your binary test checks for the presence of that bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:709 dongsheng@627: msgid "" dongsheng@627: "You fixed a bug in a rush, and now it's time to close the entry in your " dongsheng@627: "team's bug database. The bug database requires a changeset ID when you close " dongsheng@627: "an entry, but you don't remember which changeset you fixed the bug in. Once " dongsheng@627: "again, your binary test checks for the presence of the bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:716 dongsheng@627: msgid "" dongsheng@627: "Your software works correctly, but runs 15% slower than the last time you " dongsheng@627: "measured it. You want to know which changeset introduced the performance " dongsheng@627: "regression. In this case, your binary test measures the performance of your " dongsheng@627: "software, to see whether it's <quote>fast</quote> or <quote>slow</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:723 dongsheng@627: msgid "" dongsheng@627: "The sizes of the components of your project that you ship exploded recently, " dongsheng@627: "and you suspect that something changed in the way you build your project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:728 dongsheng@627: msgid "" dongsheng@627: "From these examples, it should be clear that the <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command> command is not useful only for finding the sources of bugs. " dongsheng@627: "You can use it to find any <quote>emergent property</quote> of a repository " dongsheng@627: "(anything that you can't find from a simple text search of the files in the " dongsheng@627: "tree) for which you can write a binary test." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:735 dongsheng@627: msgid "" dongsheng@627: "We'll introduce a little bit of terminology here, just to make it clear which " dongsheng@627: "parts of the search process are your responsibility, and which are " dongsheng@627: "Mercurial's. A <emphasis>test</emphasis> is something that <emphasis>you</" dongsheng@627: "emphasis> run when <command role=\"hg-cmd\">hg bisect</command> chooses a " dongsheng@627: "changeset. A <emphasis>probe</emphasis> is what <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command> runs to tell whether a revision is good. Finally, we'll use " dongsheng@627: "the word <quote>bisect</quote>, as both a noun and a verb, to stand in for " dongsheng@627: "the phrase <quote>search using the <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command> command</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:748 dongsheng@627: msgid "" dongsheng@627: "One simple way to automate the searching process would be simply to probe " dongsheng@627: "every changeset. However, this scales poorly. If it took ten minutes to " dongsheng@627: "test a single changeset, and you had 10,000 changesets in your repository, " dongsheng@627: "the exhaustive approach would take on average 35 <emphasis>days</emphasis> to " dongsheng@627: "find the changeset that introduced a bug. Even if you knew that the bug was " dongsheng@627: "introduced by one of the last 500 changesets, and limited your search to " dongsheng@627: "those, you'd still be looking at over 40 hours to find the changeset that " dongsheng@627: "introduced your bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:758 dongsheng@627: msgid "" dongsheng@627: "What the <command role=\"hg-cmd\">hg bisect</command> command does is use its " dongsheng@627: "knowledge of the <quote>shape</quote> of your project's revision history to " dongsheng@627: "perform a search in time proportional to the <emphasis>logarithm</emphasis> " dongsheng@627: "of the number of changesets to check (the kind of search it performs is " dongsheng@627: "called a dichotomic search). With this approach, searching through 10,000 " dongsheng@627: "changesets will take less than three hours, even at ten minutes per test (the " dongsheng@627: "search will require about 14 tests). Limit your search to the last hundred " dongsheng@627: "changesets, and it will take only about an hour (roughly seven tests)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:769 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg bisect</command> command is aware of the " dongsheng@627: "<quote>branchy</quote> nature of a Mercurial project's revision history, so " dongsheng@627: "it has no problems dealing with branches, merges, or multiple heads in a " dongsheng@627: "repository. It can prune entire branches of history with a single probe, " dongsheng@627: "which is how it operates so efficiently." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:777 dongsheng@627: msgid "Using the <command role=\"hg-cmd\">hg bisect</command> command" dongsheng@635: msgstr "使用命令 <command role=\"hg-cmd\">hg bisect</command>" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:780 dongsheng@627: msgid "" dongsheng@627: "Here's an example of <command role=\"hg-cmd\">hg bisect</command> in action." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch09-undo.xml:784 dongsheng@627: msgid "" dongsheng@627: "In versions 0.9.5 and earlier of Mercurial, <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command> was not a core command: it was distributed with Mercurial as " dongsheng@627: "an extension. This section describes the built-in command, not the old " dongsheng@627: "extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:791 dongsheng@627: msgid "" dongsheng@627: "Now let's create a repository, so that we can try out the <command role=\"hg-" dongsheng@627: "cmd\">hg bisect</command> command in isolation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:797 dongsheng@627: msgid "" dongsheng@627: "We'll simulate a project that has a bug in it in a simple-minded way: create " dongsheng@627: "trivial changes in a loop, and nominate one specific change that will have " dongsheng@627: "the <quote>bug</quote>. This loop creates 35 changesets, each adding a " dongsheng@627: "single file to the repository. We'll represent our <quote>bug</quote> with a " dongsheng@627: "file that contains the text <quote>i have a gub</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:807 dongsheng@627: msgid "" dongsheng@627: "The next thing that we'd like to do is figure out how to use the <command " dongsheng@627: "role=\"hg-cmd\">hg bisect</command> command. We can use Mercurial's normal " dongsheng@627: "built-in help mechanism for this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:814 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg bisect</command> command works in steps. " dongsheng@627: "Each step proceeds as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:817 dongsheng@627: msgid "You run your binary test." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:819 dongsheng@627: msgid "" dongsheng@627: "If the test succeeded, you tell <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "by running the <command role=\"hg-cmd\">hg bisect good</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:824 dongsheng@627: msgid "" dongsheng@627: "If it failed, run the <command role=\"hg-cmd\">hg bisect bad</command> " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:828 dongsheng@627: msgid "" dongsheng@627: "The command uses your information to decide which changeset to test next." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:831 dongsheng@627: msgid "" dongsheng@627: "It updates the working directory to that changeset, and the process begins " dongsheng@627: "again." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:834 dongsheng@627: msgid "" dongsheng@627: "The process ends when <command role=\"hg-cmd\">hg bisect</command> identifies " dongsheng@627: "a unique changeset that marks the point where your test transitioned from " dongsheng@627: "<quote>succeeding</quote> to <quote>failing</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:839 dongsheng@627: msgid "" dongsheng@627: "To start the search, we must run the <command role=\"hg-cmd\">hg bisect --" dongsheng@627: "reset</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:844 dongsheng@627: msgid "" dongsheng@627: "In our case, the binary test we use is simple: we check to see if any file in " dongsheng@627: "the repository contains the string <quote>i have a gub</quote>. If it does, " dongsheng@627: "this changeset contains the change that <quote>caused the bug</quote>. By " dongsheng@627: "convention, a changeset that has the property we're searching for is " dongsheng@627: "<quote>bad</quote>, while one that doesn't is <quote>good</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:852 dongsheng@627: msgid "" dongsheng@627: "Most of the time, the revision to which the working directory is synced " dongsheng@627: "(usually the tip) already exhibits the problem introduced by the buggy " dongsheng@627: "change, so we'll mark it as <quote>bad</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:859 dongsheng@627: msgid "" dongsheng@627: "Our next task is to nominate a changeset that we know <emphasis>doesn't</" dongsheng@627: "emphasis> have the bug; the <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "command will <quote>bracket</quote> its search between the first pair of good " dongsheng@627: "and bad changesets. In our case, we know that revision 10 didn't have the " dongsheng@627: "bug. (I'll have more words about choosing the first <quote>good</quote> " dongsheng@627: "changeset later.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:869 dongsheng@627: msgid "Notice that this command printed some output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:871 dongsheng@627: msgid "" dongsheng@627: "It told us how many changesets it must consider before it can identify the " dongsheng@627: "one that introduced the bug, and how many tests that will require." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:875 dongsheng@627: msgid "" dongsheng@627: "It updated the working directory to the next changeset to test, and told us " dongsheng@627: "which changeset it's testing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:880 dongsheng@627: msgid "" dongsheng@627: "We now run our test in the working directory. We use the <command>grep</" dongsheng@627: "command> command to see if our <quote>bad</quote> file is present in the " dongsheng@627: "working directory. If it is, this revision is bad; if not, this revision is " dongsheng@627: "good. &interaction.bisect.search.step1;" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:886 dongsheng@627: msgid "" dongsheng@627: "This test looks like a perfect candidate for automation, so let's turn it " dongsheng@627: "into a shell function." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:890 dongsheng@627: msgid "" dongsheng@627: "We can now run an entire test step with a single command, <literal>mytest</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:895 dongsheng@627: msgid "A few more invocations of our canned test step command, and we're done." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:900 dongsheng@627: msgid "" dongsheng@627: "Even though we had 40 changesets to search through, the <command role=\"hg-cmd" dongsheng@627: "\">hg bisect</command> command let us find the changeset that introduced our " dongsheng@627: "<quote>bug</quote> with only five tests. Because the number of tests that " dongsheng@627: "the <command role=\"hg-cmd\">hg bisect</command> command performs grows " dongsheng@627: "logarithmically with the number of changesets to search, the advantage that " dongsheng@627: "it has over the <quote>brute force</quote> search approach increases with " dongsheng@627: "every changeset you add." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:911 dongsheng@627: msgid "Cleaning up after your search" dongsheng@635: msgstr "搜索后的清理" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:913 dongsheng@627: msgid "" dongsheng@627: "When you're finished using the <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "command in a repository, you can use the <command role=\"hg-cmd\">hg bisect " dongsheng@627: "reset</command> command to drop the information it was using to drive your " dongsheng@627: "search. The command doesn't use much space, so it doesn't matter if you " dongsheng@627: "forget to run this command. However, <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command> won't let you start a new search in that repository until you do a " dongsheng@627: "<command role=\"hg-cmd\">hg bisect reset</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:928 dongsheng@627: msgid "Tips for finding bugs effectively" dongsheng@635: msgstr "有效查找问题的技巧" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:931 dongsheng@627: msgid "Give consistent input" dongsheng@635: msgstr "给出一致的输入" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:933 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg bisect</command> command requires that you " dongsheng@627: "correctly report the result of every test you perform. If you tell it that a " dongsheng@627: "test failed when it really succeeded, it <emphasis>might</emphasis> be able " dongsheng@627: "to detect the inconsistency. If it can identify an inconsistency in your " dongsheng@627: "reports, it will tell you that a particular changeset is both good and bad. " dongsheng@627: "However, it can't do this perfectly; it's about as likely to report the wrong " dongsheng@627: "changeset as the source of the bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:945 dongsheng@627: msgid "Automate as much as possible" dongsheng@635: msgstr "尽量自动" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:947 dongsheng@627: msgid "" dongsheng@627: "When I started using the <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "command, I tried a few times to run my tests by hand, on the command line. " dongsheng@627: "This is an approach that I, at least, am not suited to. After a few tries, I " dongsheng@627: "found that I was making enough mistakes that I was having to restart my " dongsheng@627: "searches several times before finally getting correct results." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:955 dongsheng@627: msgid "" dongsheng@627: "My initial problems with driving the <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command> command by hand occurred even with simple searches on small " dongsheng@627: "repositories; if the problem you're looking for is more subtle, or the number " dongsheng@627: "of tests that <command role=\"hg-cmd\">hg bisect</command> must perform " dongsheng@627: "increases, the likelihood of operator error ruining the search is much " dongsheng@627: "higher. Once I started automating my tests, I had much better results." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:964 dongsheng@627: msgid "The key to automated testing is twofold:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:966 dongsheng@627: msgid "always test for the same symptom, and" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:968 dongsheng@627: msgid "" dongsheng@627: "always feed consistent input to the <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:971 dongsheng@627: msgid "" dongsheng@627: "In my tutorial example above, the <command>grep</command> command tests for " dongsheng@627: "the symptom, and the <literal>if</literal> statement takes the result of this " dongsheng@627: "check and ensures that we always feed the same input to the <command role=" dongsheng@627: "\"hg-cmd\">hg bisect</command> command. The <literal>mytest</literal> " dongsheng@627: "function marries these together in a reproducible way, so that every test is " dongsheng@627: "uniform and consistent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:981 dongsheng@627: msgid "Check your results" dongsheng@635: msgstr "检查你的结果" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:983 dongsheng@627: msgid "" dongsheng@627: "Because the output of a <command role=\"hg-cmd\">hg bisect</command> search " dongsheng@627: "is only as good as the input you give it, don't take the changeset it reports " dongsheng@627: "as the absolute truth. A simple way to cross-check its report is to manually " dongsheng@627: "run your test at each of the following changesets:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:989 dongsheng@627: msgid "" dongsheng@627: "The changeset that it reports as the first bad revision. Your test should " dongsheng@627: "still report this as bad." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:993 dongsheng@627: msgid "" dongsheng@627: "The parent of that changeset (either parent, if it's a merge). Your test " dongsheng@627: "should report this changeset as good." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:997 dongsheng@627: msgid "" dongsheng@627: "A child of that changeset. Your test should report this changeset as bad." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:1003 dongsheng@627: msgid "Beware interference between bugs" dongsheng@635: msgstr "谨防问题之间的冲突" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1005 dongsheng@627: msgid "" dongsheng@627: "It's possible that your search for one bug could be disrupted by the presence " dongsheng@627: "of another. For example, let's say your software crashes at revision 100, " dongsheng@627: "and worked correctly at revision 50. Unknown to you, someone else introduced " dongsheng@627: "a different crashing bug at revision 60, and fixed it at revision 80. This " dongsheng@627: "could distort your results in one of several ways." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1013 dongsheng@627: msgid "" dongsheng@627: "It is possible that this other bug completely <quote>masks</quote> yours, " dongsheng@627: "which is to say that it occurs before your bug has a chance to manifest " dongsheng@627: "itself. If you can't avoid that other bug (for example, it prevents your " dongsheng@627: "project from building), and so can't tell whether your bug is present in a " dongsheng@627: "particular changeset, the <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "command cannot help you directly. Instead, you can mark a changeset as " dongsheng@627: "untested by running <command role=\"hg-cmd\">hg bisect --skip</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1023 dongsheng@627: msgid "" dongsheng@627: "A different problem could arise if your test for a bug's presence is not " dongsheng@627: "specific enough. If you check for <quote>my program crashes</quote>, then " dongsheng@627: "both your crashing bug and an unrelated crashing bug that masks it will look " dongsheng@627: "like the same thing, and mislead <command role=\"hg-cmd\">hg bisect</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1030 dongsheng@627: msgid "" dongsheng@627: "Another useful situation in which to use <command role=\"hg-cmd\">hg bisect --" dongsheng@627: "skip</command> is if you can't test a revision because your project was in a " dongsheng@627: "broken and hence untestable state at that revision, perhaps because someone " dongsheng@627: "checked in a change that prevented the project from building." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:1039 dongsheng@627: msgid "Bracket your search lazily" dongsheng@635: msgstr "减少你的查找工作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1041 dongsheng@627: msgid "" dongsheng@627: "Choosing the first <quote>good</quote> and <quote>bad</quote> changesets that " dongsheng@627: "will mark the end points of your search is often easy, but it bears a little " dongsheng@627: "discussion nevertheless. From the perspective of <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command>, the <quote>newest</quote> changeset is conventionally " dongsheng@627: "<quote>bad</quote>, and the older changeset is <quote>good</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1049 dongsheng@627: msgid "" dongsheng@627: "If you're having trouble remembering when a suitable <quote>good</quote> " dongsheng@627: "change was, so that you can tell <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command>, you could do worse than testing changesets at random. Just " dongsheng@627: "remember to eliminate contenders that can't possibly exhibit the bug (perhaps " dongsheng@627: "because the feature with the bug isn't present yet) and those where another " dongsheng@627: "problem masks the bug (as I discussed above)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1058 dongsheng@627: msgid "" dongsheng@627: "Even if you end up <quote>early</quote> by thousands of changesets or months " dongsheng@627: "of history, you will only add a handful of tests to the total number that " dongsheng@627: "<command role=\"hg-cmd\">hg bisect</command> must perform, thanks to its " dongsheng@627: "logarithmic behaviour." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch10-hook.xml:5 dongsheng@627: msgid "Handling repository events with hooks" dongsheng@627: msgstr "使用钩子处理版本库事件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch10-hook.xml:7 dongsheng@627: msgid "" dongsheng@627: "Mercurial offers a powerful mechanism to let you perform automated actions in " dongsheng@627: "response to events that occur in a repository. In some cases, you can even " dongsheng@627: "control Mercurial's response to those events." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch10-hook.xml:12 dongsheng@627: msgid "" dongsheng@627: "The name Mercurial uses for one of these actions is a <emphasis>hook</" dongsheng@627: "emphasis>. Hooks are called <quote>triggers</quote> in some revision control " dongsheng@627: "systems, but the two names refer to the same idea." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:18 dongsheng@627: msgid "An overview of hooks in Mercurial" dongsheng@635: msgstr "Mercurial 钩子概述" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:20 dongsheng@627: msgid "" dongsheng@627: "Here is a brief list of the hooks that Mercurial supports. We will revisit " dongsheng@627: "each of these hooks in more detail later, in section <xref linkend=\"sec.hook." dongsheng@627: "ref\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:25 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">changegroup</literal>: This is run after a group of " dongsheng@627: "changesets has been brought into the repository from elsewhere." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:29 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">commit</literal>: This is run after a new changeset " dongsheng@627: "has been created in the local repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:33 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">incoming</literal>: This is run once for each new " dongsheng@627: "changeset that is brought into the repository from elsewhere. Notice the " dongsheng@627: "difference from <literal role=\"hook\">changegroup</literal>, which is run " dongsheng@627: "once per <emphasis>group</emphasis> of changesets brought in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:40 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">outgoing</literal>: This is run after a group of " dongsheng@627: "changesets has been transmitted from this repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:44 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">prechangegroup</literal>: This is run before starting " dongsheng@627: "to bring a group of changesets into the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:49 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">precommit</literal>: Controlling. This is run before " dongsheng@627: "starting a commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:53 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">preoutgoing</literal>: Controlling. This is run before " dongsheng@627: "starting to transmit a group of changesets from this repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:58 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretag</literal>: Controlling. This is run before " dongsheng@627: "creating a tag." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:62 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretxnchangegroup</literal>: Controlling. This is run " dongsheng@627: "after a group of changesets has been brought into the local repository from " dongsheng@627: "another, but before the transaction completes that will make the changes " dongsheng@627: "permanent in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:70 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretxncommit</literal>: Controlling. This is run after " dongsheng@627: "a new changeset has been created in the local repository, but before the " dongsheng@627: "transaction completes that will make it permanent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:76 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">preupdate</literal>: Controlling. This is run before " dongsheng@627: "starting an update or merge of the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:81 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">tag</literal>: This is run after a tag is created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:85 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">update</literal>: This is run after an update or merge " dongsheng@627: "of the working directory has finished." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:90 dongsheng@627: msgid "" dongsheng@627: "Each of the hooks whose description begins with the word <quote>Controlling</" dongsheng@627: "quote> has the ability to determine whether an activity can proceed. If the " dongsheng@627: "hook succeeds, the activity may proceed; if it fails, the activity is either " dongsheng@627: "not permitted or undone, depending on the hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:99 dongsheng@627: msgid "Hooks and security" dongsheng@635: msgstr "钩子与安全性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:102 dongsheng@627: msgid "Hooks are run with your privileges" dongsheng@635: msgstr "钩子以你的特权执行" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:104 dongsheng@627: msgid "" dongsheng@627: "When you run a Mercurial command in a repository, and the command causes a " dongsheng@627: "hook to run, that hook runs on <emphasis>your</emphasis> system, under " dongsheng@627: "<emphasis>your</emphasis> user account, with <emphasis>your</emphasis> " dongsheng@627: "privilege level. Since hooks are arbitrary pieces of executable code, you " dongsheng@627: "should treat them with an appropriate level of suspicion. Do not install a " dongsheng@627: "hook unless you are confident that you know who created it and what it does." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:115 dongsheng@627: msgid "" dongsheng@627: "In some cases, you may be exposed to hooks that you did not install " dongsheng@627: "yourself. If you work with Mercurial on an unfamiliar system, Mercurial will " dongsheng@627: "run hooks defined in that system's global <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>\\ file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:122 dongsheng@627: msgid "" dongsheng@627: "If you are working with a repository owned by another user, Mercurial can run " dongsheng@627: "hooks defined in that user's repository, but it will still run them as " dongsheng@627: "<quote>you</quote>. For example, if you <command role=\"hg-cmd\">hg pull</" dongsheng@627: "command> from that repository, and its <filename role=\"special\">.hg/hgrc</" dongsheng@627: "filename> defines a local <literal role=\"hook\">outgoing</literal> hook, " dongsheng@627: "that hook will run under your user account, even though you don't own that " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch10-hook.xml:134 dongsheng@627: msgid "" dongsheng@627: "This only applies if you are pulling from a repository on a local or network " dongsheng@627: "filesystem. If you're pulling over http or ssh, any <literal role=\"hook" dongsheng@627: "\">outgoing</literal> hook will run under whatever account is executing the " dongsheng@627: "server process, on the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:142 dongsheng@627: msgid "" dongsheng@627: "XXX To see what hooks are defined in a repository, use the <command role=\"hg-" dongsheng@627: "cmd\">hg config hooks</command> command. If you are working in one " dongsheng@627: "repository, but talking to another that you do not own (e.g. using <command " dongsheng@627: "role=\"hg-cmd\">hg pull</command> or <command role=\"hg-cmd\">hg incoming</" dongsheng@627: "command>), remember that it is the other repository's hooks you should be " dongsheng@627: "checking, not your own." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:153 dongsheng@627: msgid "Hooks do not propagate" dongsheng@635: msgstr "钩子不会传播" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:155 dongsheng@627: msgid "" dongsheng@627: "In Mercurial, hooks are not revision controlled, and do not propagate when " dongsheng@627: "you clone, or pull from, a repository. The reason for this is simple: a hook " dongsheng@627: "is a completely arbitrary piece of executable code. It runs under your user " dongsheng@627: "identity, with your privilege level, on your machine." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:162 dongsheng@627: msgid "" dongsheng@627: "It would be extremely reckless for any distributed revision control system to " dongsheng@627: "implement revision-controlled hooks, as this would offer an easily " dongsheng@627: "exploitable way to subvert the accounts of users of the revision control " dongsheng@627: "system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:168 dongsheng@627: msgid "" dongsheng@627: "Since Mercurial does not propagate hooks, if you are collaborating with other " dongsheng@627: "people on a common project, you should not assume that they are using the " dongsheng@627: "same Mercurial hooks as you are, or that theirs are correctly configured. " dongsheng@627: "You should document the hooks you expect people to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:175 dongsheng@627: msgid "" dongsheng@627: "In a corporate intranet, this is somewhat easier to control, as you can for " dongsheng@627: "example provide a <quote>standard</quote> installation of Mercurial on an NFS " dongsheng@627: "filesystem, and use a site-wide <filename role=\"special\"> /.hgrc</filename>" dongsheng@627: "\\ file to define hooks that all users will see. However, this too has its " dongsheng@627: "limits; see below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:185 dongsheng@627: msgid "Hooks can be overridden" dongsheng@635: msgstr "钩子可以被覆盖" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:187 dongsheng@627: msgid "" dongsheng@627: "Mercurial allows you to override a hook definition by redefining the hook. " dongsheng@627: "You can disable it by setting its value to the empty string, or change its " dongsheng@627: "behaviour as you wish." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:192 dongsheng@627: msgid "" dongsheng@627: "If you deploy a system- or site-wide <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>\\ file that defines some hooks, you should thus understand that " dongsheng@627: "your users can disable or override those hooks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:200 dongsheng@627: msgid "Ensuring that critical hooks are run" dongsheng@635: msgstr "确保关键钩子的执行" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:202 dongsheng@627: msgid "" dongsheng@627: "Sometimes you may want to enforce a policy that you do not want others to be " dongsheng@627: "able to work around. For example, you may have a requirement that every " dongsheng@627: "changeset must pass a rigorous set of tests. Defining this requirement via a " dongsheng@627: "hook in a site-wide <filename role=\"special\"> /.hgrc</filename>\\ won't " dongsheng@627: "work for remote users on laptops, and of course local users can subvert it at " dongsheng@627: "will by overriding the hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:211 dongsheng@627: msgid "" dongsheng@627: "Instead, you can set up your policies for use of Mercurial so that people are " dongsheng@627: "expected to propagate changes through a well-known <quote>canonical</quote> " dongsheng@627: "server that you have locked down and configured appropriately." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:217 dongsheng@627: msgid "" dongsheng@627: "One way to do this is via a combination of social engineering and " dongsheng@627: "technology. Set up a restricted-access account; users can push changes over " dongsheng@627: "the network to repositories managed by this account, but they cannot log into " dongsheng@627: "the account and run normal shell commands. In this scenario, a user can " dongsheng@627: "commit a changeset that contains any old garbage they want." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:226 dongsheng@627: msgid "" dongsheng@627: "When someone pushes a changeset to the server that everyone pulls from, the " dongsheng@627: "server will test the changeset before it accepts it as permanent, and reject " dongsheng@627: "it if it fails to pass the test suite. If people only pull changes from this " dongsheng@627: "filtering server, it will serve to ensure that all changes that people pull " dongsheng@627: "have been automatically vetted." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:237 dongsheng@627: msgid "Care with <literal>pretxn</literal> hooks in a shared-access repository" dongsheng@635: msgstr "在共享版本库中注意 <literal>pretxn</literal> 钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:240 dongsheng@627: msgid "" dongsheng@627: "If you want to use hooks to do some automated work in a repository that a " dongsheng@627: "number of people have shared access to, you need to be careful in how you do " dongsheng@627: "this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:245 dongsheng@627: msgid "" dongsheng@627: "Mercurial only locks a repository when it is writing to the repository, and " dongsheng@627: "only the parts of Mercurial that write to the repository pay attention to " dongsheng@627: "locks. Write locks are necessary to prevent multiple simultaneous writers " dongsheng@627: "from scribbling on each other's work, corrupting the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:252 dongsheng@627: msgid "" dongsheng@627: "Because Mercurial is careful with the order in which it reads and writes " dongsheng@627: "data, it does not need to acquire a lock when it wants to read data from the " dongsheng@627: "repository. The parts of Mercurial that read from the repository never pay " dongsheng@627: "attention to locks. This lockless reading scheme greatly increases " dongsheng@627: "performance and concurrency." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:260 dongsheng@627: msgid "" dongsheng@627: "With great performance comes a trade-off, though, one which has the potential " dongsheng@627: "to cause you trouble unless you're aware of it. To describe this requires a " dongsheng@627: "little detail about how Mercurial adds changesets to a repository and reads " dongsheng@627: "those changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:267 dongsheng@627: msgid "" dongsheng@627: "When Mercurial <emphasis>writes</emphasis> metadata, it writes it straight " dongsheng@627: "into the destination file. It writes file data first, then manifest data " dongsheng@627: "(which contains pointers to the new file data), then changelog data (which " dongsheng@627: "contains pointers to the new manifest data). Before the first write to each " dongsheng@627: "file, it stores a record of where the end of the file was in its transaction " dongsheng@627: "log. If the transaction must be rolled back, Mercurial simply truncates each " dongsheng@627: "file back to the size it was before the transaction began." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:278 dongsheng@627: msgid "" dongsheng@627: "When Mercurial <emphasis>reads</emphasis> metadata, it reads the changelog " dongsheng@627: "first, then everything else. Since a reader will only access parts of the " dongsheng@627: "manifest or file metadata that it can see in the changelog, it can never see " dongsheng@627: "partially written data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:284 dongsheng@627: msgid "" dongsheng@627: "Some controlling hooks (<literal role=\"hook\">pretxncommit</literal> and " dongsheng@627: "<literal role=\"hook\">pretxnchangegroup</literal>) run when a transaction is " dongsheng@627: "almost complete. All of the metadata has been written, but Mercurial can " dongsheng@627: "still roll the transaction back and cause the newly-written data to disappear." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:292 dongsheng@627: msgid "" dongsheng@627: "If one of these hooks runs for long, it opens a window of time during which a " dongsheng@627: "reader can see the metadata for changesets that are not yet permanent, and " dongsheng@627: "should not be thought of as <quote>really there</quote>. The longer the hook " dongsheng@627: "runs, the longer that window is open." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:300 dongsheng@627: msgid "The problem illustrated" dongsheng@635: msgstr "问题的演示" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:302 dongsheng@627: msgid "" dongsheng@627: "In principle, a good use for the <literal role=\"hook\">pretxnchangegroup</" dongsheng@627: "literal> hook would be to automatically build and test incoming changes " dongsheng@627: "before they are accepted into a central repository. This could let you " dongsheng@627: "guarantee that nobody can push changes to this repository that <quote>break " dongsheng@627: "the build</quote>. But if a client can pull changes while they're being " dongsheng@627: "tested, the usefulness of the test is zero; an unsuspecting someone can pull " dongsheng@627: "untested changes, potentially breaking their build." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:313 dongsheng@627: msgid "" dongsheng@627: "The safest technological answer to this challenge is to set up such a " dongsheng@627: "<quote>gatekeeper</quote> repository as <emphasis>unidirectional</emphasis>. " dongsheng@627: "Let it take changes pushed in from the outside, but do not allow anyone to " dongsheng@627: "pull changes from it (use the <literal role=\"hook\">preoutgoing</literal> " dongsheng@627: "hook to lock it down). Configure a <literal role=\"hook\">changegroup</" dongsheng@627: "literal> hook so that if a build or test succeeds, the hook will push the new " dongsheng@627: "changes out to another repository that people <emphasis>can</emphasis> pull " dongsheng@627: "from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:325 dongsheng@627: msgid "" dongsheng@627: "In practice, putting a centralised bottleneck like this in place is not often " dongsheng@627: "a good idea, and transaction visibility has nothing to do with the problem. " dongsheng@627: "As the size of a project&emdash;and the time it takes to build and " dongsheng@627: "test&emdash;grows, you rapidly run into a wall with this <quote>try before " dongsheng@627: "you buy</quote> approach, where you have more changesets to test than time in " dongsheng@627: "which to deal with them. The inevitable result is frustration on the part of " dongsheng@627: "all involved." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:336 dongsheng@627: msgid "" dongsheng@627: "An approach that scales better is to get people to build and test before they " dongsheng@627: "push, then run automated builds and tests centrally <emphasis>after</" dongsheng@627: "emphasis> a push, to be sure all is well. The advantage of this approach is " dongsheng@627: "that it does not impose a limit on the rate at which the repository can " dongsheng@627: "accept changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:347 dongsheng@627: msgid "A short tutorial on using hooks" dongsheng@635: msgstr "使用钩子的简短指南" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:349 dongsheng@627: msgid "" dongsheng@627: "It is easy to write a Mercurial hook. Let's start with a hook that runs when " dongsheng@627: "you finish a <command role=\"hg-cmd\">hg commit</command>, and simply prints " dongsheng@627: "the hash of the changeset you just created. The hook is called <literal role=" dongsheng@627: "\"hook\">commit</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:356 dongsheng@627: msgid "All hooks follow the pattern in this example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:360 dongsheng@627: msgid "" dongsheng@627: "You add an entry to the <literal role=\"rc-hooks\">hooks</literal> section of " dongsheng@627: "your <filename role=\"special\"> /.hgrc</filename>. On the left is the name " dongsheng@627: "of the event to trigger on; on the right is the action to take. As you can " dongsheng@627: "see, you can run an arbitrary shell command in a hook. Mercurial passes " dongsheng@627: "extra information to the hook using environment variables (look for " dongsheng@627: "<envar>HG_NODE</envar> in the example)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:370 dongsheng@627: msgid "Performing multiple actions per event" dongsheng@635: msgstr "每个事件执行多个操作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:372 dongsheng@627: msgid "" dongsheng@627: "Quite often, you will want to define more than one hook for a particular kind " dongsheng@627: "of event, as shown below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:377 dongsheng@627: msgid "" dongsheng@627: "Mercurial lets you do this by adding an <emphasis>extension</emphasis> to the " dongsheng@627: "end of a hook's name. You extend a hook's name by giving the name of the " dongsheng@627: "hook, followed by a full stop (the <quote><literal>.</literal></quote> " dongsheng@627: "character), followed by some more text of your choosing. For example, " dongsheng@627: "Mercurial will run both <literal>commit.foo</literal> and <literal>commit." dongsheng@627: "bar</literal> when the <literal>commit</literal> event occurs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:388 dongsheng@627: msgid "" dongsheng@627: "To give a well-defined order of execution when there are multiple hooks " dongsheng@627: "defined for an event, Mercurial sorts hooks by extension, and executes the " dongsheng@627: "hook commands in this sorted order. In the above example, it will execute " dongsheng@627: "<literal>commit.bar</literal> before <literal>commit.foo</literal>, and " dongsheng@627: "<literal>commit</literal> before both." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:397 dongsheng@627: msgid "" dongsheng@627: "It is a good idea to use a somewhat descriptive extension when you define a " dongsheng@627: "new hook. This will help you to remember what the hook was for. If the hook " dongsheng@627: "fails, you'll get an error message that contains the hook name and extension, " dongsheng@627: "so using a descriptive extension could give you an immediate hint as to why " dongsheng@627: "the hook failed (see section <xref linkend=\"sec.hook.perm\"/> for an " dongsheng@627: "example)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:408 dongsheng@627: msgid "Controlling whether an activity can proceed" dongsheng@635: msgstr "控制处理的活动" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:410 dongsheng@627: msgid "" dongsheng@627: "In our earlier examples, we used the <literal role=\"hook\">commit</literal> " dongsheng@627: "hook, which is run after a commit has completed. This is one of several " dongsheng@627: "Mercurial hooks that run after an activity finishes. Such hooks have no way " dongsheng@627: "of influencing the activity itself." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:417 dongsheng@627: msgid "" dongsheng@627: "Mercurial defines a number of events that occur before an activity starts; or " dongsheng@627: "after it starts, but before it finishes. Hooks that trigger on these events " dongsheng@627: "have the added ability to choose whether the activity can continue, or will " dongsheng@627: "abort." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:423 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hook\">pretxncommit</literal> hook runs after a commit " dongsheng@627: "has all but completed. In other words, the metadata representing the " dongsheng@627: "changeset has been written out to disk, but the transaction has not yet been " dongsheng@627: "allowed to complete. The <literal role=\"hook\">pretxncommit</literal> hook " dongsheng@627: "has the ability to decide whether the transaction can complete, or must be " dongsheng@627: "rolled back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:432 dongsheng@627: msgid "" dongsheng@627: "If the <literal role=\"hook\">pretxncommit</literal> hook exits with a status " dongsheng@627: "code of zero, the transaction is allowed to complete; the commit finishes; " dongsheng@627: "and the <literal role=\"hook\">commit</literal> hook is run. If the <literal " dongsheng@627: "role=\"hook\">pretxncommit</literal> hook exits with a non-zero status code, " dongsheng@627: "the transaction is rolled back; the metadata representing the changeset is " dongsheng@627: "erased; and the <literal role=\"hook\">commit</literal> hook is not run." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:444 dongsheng@627: msgid "" dongsheng@627: "The hook in the example above checks that a commit comment contains a bug " dongsheng@627: "ID. If it does, the commit can complete. If not, the commit is rolled back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:452 dongsheng@627: msgid "Writing your own hooks" dongsheng@635: msgstr "编写钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:454 dongsheng@627: msgid "" dongsheng@627: "When you are writing a hook, you might find it useful to run Mercurial either " dongsheng@627: "with the <option role=\"hg-opt-global\">-v</option> option, or the <envar " dongsheng@627: "role=\"rc-item-ui\">verbose</envar> config item set to <quote>true</quote>. " dongsheng@627: "When you do so, Mercurial will print a message before it calls each hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:463 dongsheng@627: msgid "Choosing how your hook should run" dongsheng@635: msgstr "选择钩子的执行方式" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:465 dongsheng@627: msgid "" dongsheng@627: "You can write a hook either as a normal program&emdash;typically a shell " dongsheng@627: "script&emdash;or as a Python function that is executed within the Mercurial " dongsheng@627: "process." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:470 dongsheng@627: msgid "" dongsheng@627: "Writing a hook as an external program has the advantage that it requires no " dongsheng@627: "knowledge of Mercurial's internals. You can call normal Mercurial commands " dongsheng@627: "to get any added information you need. The trade-off is that external hooks " dongsheng@627: "are slower than in-process hooks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:477 dongsheng@627: msgid "" dongsheng@627: "An in-process Python hook has complete access to the Mercurial API, and does " dongsheng@627: "not <quote>shell out</quote> to another process, so it is inherently faster " dongsheng@627: "than an external hook. It is also easier to obtain much of the information " dongsheng@627: "that a hook requires by using the Mercurial API than by running Mercurial " dongsheng@627: "commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:485 dongsheng@627: msgid "" dongsheng@627: "If you are comfortable with Python, or require high performance, writing your " dongsheng@627: "hooks in Python may be a good choice. However, when you have a " dongsheng@627: "straightforward hook to write and you don't need to care about performance " dongsheng@627: "(probably the majority of hooks), a shell script is perfectly fine." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:494 dongsheng@627: msgid "Hook parameters" dongsheng@635: msgstr "钩子的参数" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:496 dongsheng@627: msgid "" dongsheng@627: "Mercurial calls each hook with a set of well-defined parameters. In Python, " dongsheng@627: "a parameter is passed as a keyword argument to your hook function. For an " dongsheng@627: "external program, a parameter is passed as an environment variable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:502 dongsheng@627: msgid "" dongsheng@627: "Whether your hook is written in Python or as a shell script, the hook-" dongsheng@627: "specific parameter names and values will be the same. A boolean parameter " dongsheng@627: "will be represented as a boolean value in Python, but as the number 1 (for " dongsheng@627: "<quote>true</quote>) or 0 (for <quote>false</quote>) as an environment " dongsheng@627: "variable for an external hook. If a hook parameter is named <literal>foo</" dongsheng@627: "literal>, the keyword argument for a Python hook will also be named " dongsheng@627: "<literal>foo</literal>, while the environment variable for an external hook " dongsheng@627: "will be named <literal>HG_FOO</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:516 dongsheng@627: msgid "Hook return values and activity control" dongsheng@635: msgstr "钩子的返回值与活动控制" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:518 dongsheng@627: msgid "" dongsheng@627: "A hook that executes successfully must exit with a status of zero if " dongsheng@627: "external, or return boolean <quote>false</quote> if in-process. Failure is " dongsheng@627: "indicated with a non-zero exit status from an external hook, or an in-process " dongsheng@627: "hook returning boolean <quote>true</quote>. If an in-process hook raises an " dongsheng@627: "exception, the hook is considered to have failed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:526 dongsheng@627: msgid "" dongsheng@627: "For a hook that controls whether an activity can proceed, zero/false means " dongsheng@627: "<quote>allow</quote>, while non-zero/true/exception means <quote>deny</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:533 dongsheng@627: msgid "Writing an external hook" dongsheng@635: msgstr "编写外部钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:535 dongsheng@627: msgid "" dongsheng@627: "When you define an external hook in your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>\\ and the hook is run, its value is passed to your shell, which " dongsheng@627: "interprets it. This means that you can use normal shell constructs in the " dongsheng@627: "body of the hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:542 dongsheng@627: msgid "" dongsheng@627: "An executable hook is always run with its current directory set to a " dongsheng@627: "repository's root directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:546 dongsheng@627: msgid "" dongsheng@627: "Each hook parameter is passed in as an environment variable; the name is " dongsheng@627: "upper-cased, and prefixed with the string <quote><literal>HG_</literal></" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:551 dongsheng@627: msgid "" dongsheng@627: "With the exception of hook parameters, Mercurial does not set or modify any " dongsheng@627: "environment variables when running a hook. This is useful to remember if you " dongsheng@627: "are writing a site-wide hook that may be run by a number of different users " dongsheng@627: "with differing environment variables set. In multi-user situations, you " dongsheng@627: "should not rely on environment variables being set to the values you have in " dongsheng@627: "your environment when testing the hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:562 dongsheng@627: msgid "Telling Mercurial to use an in-process hook" dongsheng@635: msgstr "让 MercurialMercurial 使用进程内钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:564 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\"> /.hgrc</filename>\\ syntax for defining an in-" dongsheng@627: "process hook is slightly different than for an executable hook. The value of " dongsheng@627: "the hook must start with the text <quote><literal>python:</literal></quote>, " dongsheng@627: "and continue with the fully-qualified name of a callable object to use as the " dongsheng@627: "hook's value." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:572 dongsheng@627: msgid "" dongsheng@627: "The module in which a hook lives is automatically imported when a hook is " dongsheng@627: "run. So long as you have the module name and <envar>PYTHONPATH</envar> " dongsheng@627: "right, it should <quote>just work</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:578 dongsheng@627: msgid "" dongsheng@627: "The following <filename role=\"special\"> /.hgrc</filename>\\ example snippet " dongsheng@627: "illustrates the syntax and meaning of the notions we just described." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:584 dongsheng@627: msgid "" dongsheng@627: "When Mercurial runs the <literal>commit.example</literal> hook, it imports " dongsheng@627: "<literal>mymodule.submodule</literal>, looks for the callable object named " dongsheng@627: "<literal>myhook</literal>, and calls it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:592 dongsheng@627: msgid "Writing an in-process hook" dongsheng@635: msgstr "编写进程内钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:594 dongsheng@627: msgid "" dongsheng@627: "The simplest in-process hook does nothing, but illustrates the basic shape of " dongsheng@627: "the hook API:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:599 dongsheng@627: msgid "" dongsheng@627: "The first argument to a Python hook is always a <literal role=\"py-mod-" dongsheng@627: "mercurial.ui\">ui</literal> object. The second is a repository object; at " dongsheng@627: "the moment, it is always an instance of <literal role=\"py-mod-mercurial." dongsheng@627: "localrepo\">localrepository</literal>. Following these two arguments are " dongsheng@627: "other keyword arguments. Which ones are passed in depends on the hook being " dongsheng@627: "called, but a hook can ignore arguments it doesn't care about by dropping " dongsheng@627: "them into a keyword argument dict, as with <literal>**kwargs</literal> above." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:614 dongsheng@627: msgid "Some hook examples" dongsheng@635: msgstr "钩子样例" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:617 dongsheng@627: msgid "Writing meaningful commit messages" dongsheng@635: msgstr "编写有意义的提交日志" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:619 dongsheng@627: msgid "" dongsheng@627: "It's hard to imagine a useful commit message being very short. The simple " dongsheng@627: "<literal role=\"hook\">pretxncommit</literal> hook of the example below will " dongsheng@627: "prevent you from committing a changeset with a message that is less than ten " dongsheng@627: "bytes long." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:629 dongsheng@627: msgid "Checking for trailing whitespace" dongsheng@635: msgstr "检查行尾空格" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:631 dongsheng@627: msgid "" dongsheng@627: "An interesting use of a commit-related hook is to help you to write cleaner " dongsheng@627: "code. A simple example of <quote>cleaner code</quote> is the dictum that a " dongsheng@627: "change should not add any new lines of text that contain <quote>trailing " dongsheng@627: "whitespace</quote>. Trailing whitespace is a series of space and tab " dongsheng@627: "characters at the end of a line of text. In most cases, trailing whitespace " dongsheng@627: "is unnecessary, invisible noise, but it is occasionally problematic, and " dongsheng@627: "people often prefer to get rid of it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:642 dongsheng@627: msgid "" dongsheng@627: "You can use either the <literal role=\"hook\">precommit</literal> or <literal " dongsheng@627: "role=\"hook\">pretxncommit</literal> hook to tell whether you have a trailing " dongsheng@627: "whitespace problem. If you use the <literal role=\"hook\">precommit</" dongsheng@627: "literal> hook, the hook will not know which files you are committing, so it " dongsheng@627: "will have to check every modified file in the repository for trailing white " dongsheng@627: "space. If you want to commit a change to just the file <filename>foo</" dongsheng@627: "filename>, but the file <filename>bar</filename> contains trailing " dongsheng@627: "whitespace, doing a check in the <literal role=\"hook\">precommit</literal> " dongsheng@627: "hook will prevent you from committing <filename>foo</filename> due to the " dongsheng@627: "problem with <filename>bar</filename>. This doesn't seem right." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:658 dongsheng@627: msgid "" dongsheng@627: "Should you choose the <literal role=\"hook\">pretxncommit</literal> hook, the " dongsheng@627: "check won't occur until just before the transaction for the commit " dongsheng@627: "completes. This will allow you to check for problems only the exact files " dongsheng@627: "that are being committed. However, if you entered the commit message " dongsheng@627: "interactively and the hook fails, the transaction will roll back; you'll have " dongsheng@627: "to re-enter the commit message after you fix the trailing whitespace and run " dongsheng@627: "<command role=\"hg-cmd\">hg commit</command> again." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:671 dongsheng@627: msgid "" dongsheng@627: "In this example, we introduce a simple <literal role=\"hook\">pretxncommit</" dongsheng@627: "literal> hook that checks for trailing whitespace. This hook is short, but " dongsheng@627: "not very helpful. It exits with an error status if a change adds a line with " dongsheng@627: "trailing whitespace to any file, but does not print any information that " dongsheng@627: "might help us to identify the offending file or line. It also has the nice " dongsheng@627: "property of not paying attention to unmodified lines; only lines that " dongsheng@627: "introduce new trailing whitespace cause problems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:682 dongsheng@627: msgid "" dongsheng@627: "The above version is much more complex, but also more useful. It parses a " dongsheng@627: "unified diff to see if any lines add trailing whitespace, and prints the name " dongsheng@627: "of the file and the line number of each such occurrence. Even better, if the " dongsheng@627: "change adds trailing whitespace, this hook saves the commit comment and " dongsheng@627: "prints the name of the save file before exiting and telling Mercurial to roll " dongsheng@627: "the transaction back, so you can use the <option role=\"hg-opt-commit\">-l " dongsheng@627: "filename</option> option to <command role=\"hg-cmd\">hg commit</command> to " dongsheng@627: "reuse the saved commit message once you've corrected the problem." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:696 dongsheng@627: msgid "" dongsheng@627: "As a final aside, note in the example above the use of <command>perl</" dongsheng@627: "command>'s in-place editing feature to get rid of trailing whitespace from a " dongsheng@627: "file. This is concise and useful enough that I will reproduce it here." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:706 dongsheng@627: msgid "Bundled hooks" dongsheng@635: msgstr "内置的钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:708 dongsheng@627: msgid "" dongsheng@627: "Mercurial ships with several bundled hooks. You can find them in the " dongsheng@627: "<filename class=\"directory\">hgext</filename> directory of a Mercurial " dongsheng@627: "source tree. If you are using a Mercurial binary package, the hooks will be " dongsheng@627: "located in the <filename class=\"directory\">hgext</filename> directory of " dongsheng@627: "wherever your package installer put Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:717 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hg-ext\">acl</literal>&emdash;access control for parts of a " dongsheng@627: "repository" dongsheng@635: msgstr "<literal role=\"hg-ext\">acl</literal>&emdash;版本库的访问控制" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:720 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">acl</literal> extension lets you control which " dongsheng@627: "remote users are allowed to push changesets to a networked server. You can " dongsheng@627: "protect any portion of a repository (including the entire repo), so that a " dongsheng@627: "specific remote user can push changes that do not affect the protected " dongsheng@627: "portion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:728 dongsheng@627: msgid "" dongsheng@627: "This extension implements access control based on the identity of the user " dongsheng@627: "performing a push, <emphasis>not</emphasis> on who committed the changesets " dongsheng@627: "they're pushing. It makes sense to use this hook only if you have a locked-" dongsheng@627: "down server environment that authenticates remote users, and you want to be " dongsheng@627: "sure that only specific users are allowed to push changes to that server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:738 dongsheng@627: msgid "Configuring the <literal role=\"hook\">acl</literal> hook" dongsheng@635: msgstr "配置 <literal role=\"hook\">acl</literal> 钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:741 dongsheng@627: msgid "" dongsheng@627: "In order to manage incoming changesets, the <literal role=\"hg-ext\">acl</" dongsheng@627: "literal> hook must be used as a <literal role=\"hook\">pretxnchangegroup</" dongsheng@627: "literal> hook. This lets it see which files are modified by each incoming " dongsheng@627: "changeset, and roll back a group of changesets if they modify " dongsheng@627: "<quote>forbidden</quote> files. Example:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:751 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">acl</literal> extension is configured using " dongsheng@627: "three sections." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:755 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"rc-acl\">acl</literal> section has only one entry, <envar " dongsheng@627: "role=\"rc-item-acl\">sources</envar>, which lists the sources of incoming " dongsheng@627: "changesets that the hook should pay attention to. You don't normally need to " dongsheng@627: "configure this section." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:762 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-acl\">serve</envar>: Control incoming changesets that " dongsheng@627: "are arriving from a remote repository over http or ssh. This is the default " dongsheng@627: "value of <envar role=\"rc-item-acl\">sources</envar>, and usually the only " dongsheng@627: "setting you'll need for this configuration item." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:770 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-acl\">pull</envar>: Control incoming changesets that " dongsheng@627: "are arriving via a pull from a local repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:775 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-acl\">push</envar>: Control incoming changesets that " dongsheng@627: "are arriving via a push from a local repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:780 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-acl\">bundle</envar>: Control incoming changesets that " dongsheng@627: "are arriving from another repository via a bundle." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:786 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"rc-acl.allow\">acl.allow</literal> section controls the " dongsheng@627: "users that are allowed to add changesets to the repository. If this section " dongsheng@627: "is not present, all users that are not explicitly denied are allowed. If " dongsheng@627: "this section is present, all users that are not explicitly allowed are denied " dongsheng@627: "(so an empty section means that all users are denied)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:795 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"rc-acl.deny\">acl.deny</literal> section determines which " dongsheng@627: "users are denied from adding changesets to the repository. If this section " dongsheng@627: "is not present or is empty, no users are denied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:801 dongsheng@627: msgid "" dongsheng@627: "The syntaxes for the <literal role=\"rc-acl.allow\">acl.allow</literal> and " dongsheng@627: "<literal role=\"rc-acl.deny\">acl.deny</literal> sections are identical. On " dongsheng@627: "the left of each entry is a glob pattern that matches files or directories, " dongsheng@627: "relative to the root of the repository; on the right, a user name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:809 dongsheng@627: msgid "" dongsheng@627: "In the following example, the user <literal>docwriter</literal> can only push " dongsheng@627: "changes to the <filename class=\"directory\">docs</filename> subtree of the " dongsheng@627: "repository, while <literal>intern</literal> can push changes to any file or " dongsheng@627: "directory except <filename class=\"directory\">source/sensitive</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:821 ../en/ch10-hook.xml:1095 ../en/ch10-hook.xml:1308 dongsheng@627: msgid "Testing and troubleshooting" dongsheng@635: msgstr "测试与问题处理" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:823 dongsheng@627: msgid "" dongsheng@627: "If you want to test the <literal role=\"hg-ext\">acl</literal> hook, run it " dongsheng@627: "with Mercurial's debugging output enabled. Since you'll probably be running " dongsheng@627: "it on a server where it's not convenient (or sometimes possible) to pass in " dongsheng@627: "the <option role=\"hg-opt-global\">--debug</option> option, don't forget that " dongsheng@627: "you can enable debugging output in your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:833 dongsheng@627: msgid "" dongsheng@627: "With this enabled, the <literal role=\"hg-ext\">acl</literal> hook will print " dongsheng@627: "enough information to let you figure out why it is allowing or forbidding " dongsheng@627: "pushes from specific users." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:842 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hg-ext\">bugzilla</literal>&emdash;integration with Bugzilla" dongsheng@635: msgstr "<literal role=\"hg-ext\">bugzilla</literal>&emdash;与 Bugzilla 的集成" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:846 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">bugzilla</literal> extension adds a comment to a " dongsheng@627: "Bugzilla bug whenever it finds a reference to that bug ID in a commit " dongsheng@627: "comment. You can install this hook on a shared server, so that any time a " dongsheng@627: "remote user pushes changes to this server, the hook gets run." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:853 dongsheng@627: msgid "" dongsheng@627: "It adds a comment to the bug that looks like this (you can configure the " dongsheng@627: "contents of the comment&emdash;see below):" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:862 dongsheng@627: msgid "" dongsheng@627: "The value of this hook is that it automates the process of updating a bug any " dongsheng@627: "time a changeset refers to it. If you configure the hook properly, it makes " dongsheng@627: "it easy for people to browse straight from a Bugzilla bug to a changeset that " dongsheng@627: "refers to that bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:869 dongsheng@627: msgid "" dongsheng@627: "You can use the code in this hook as a starting point for some more exotic " dongsheng@627: "Bugzilla integration recipes. Here are a few possibilities:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:874 dongsheng@627: msgid "" dongsheng@627: "Require that every changeset pushed to the server have a valid bug ID in its " dongsheng@627: "commit comment. In this case, you'd want to configure the hook as a <literal " dongsheng@627: "role=\"hook\">pretxncommit</literal> hook. This would allow the hook to " dongsheng@627: "reject changes that didn't contain bug IDs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:882 dongsheng@627: msgid "" dongsheng@627: "Allow incoming changesets to automatically modify the <emphasis>state</" dongsheng@627: "emphasis> of a bug, as well as simply adding a comment. For example, the " dongsheng@627: "hook could recognise the string <quote>fixed bug 31337</quote> as indicating " dongsheng@627: "that it should update the state of bug 31337 to <quote>requires testing</" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:892 dongsheng@627: msgid "Configuring the <literal role=\"hook\">bugzilla</literal> hook" dongsheng@635: msgstr "配置 <literal role=\"hook\">bugzilla</literal> 钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:895 dongsheng@627: msgid "" dongsheng@627: "You should configure this hook in your server's <filename role=\"special\"> /." dongsheng@627: "hgrc</filename>\\ as an <literal role=\"hook\">incoming</literal> hook, for " dongsheng@627: "example as follows:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:903 dongsheng@627: msgid "" dongsheng@627: "Because of the specialised nature of this hook, and because Bugzilla was not " dongsheng@627: "written with this kind of integration in mind, configuring this hook is a " dongsheng@627: "somewhat involved process." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:909 dongsheng@627: msgid "" dongsheng@627: "Before you begin, you must install the MySQL bindings for Python on the host" dongsheng@627: "(s) where you'll be running the hook. If this is not available as a binary " dongsheng@627: "package for your system, you can download it from <citation>web:mysql-python</" dongsheng@627: "citation>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:916 dongsheng@627: msgid "" dongsheng@627: "Configuration information for this hook lives in the <literal role=\"rc-" dongsheng@627: "bugzilla\">bugzilla</literal> section of your <filename role=\"special\"> /." dongsheng@627: "hgrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:921 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">version</envar>: The version of Bugzilla " dongsheng@627: "installed on the server. The database schema that Bugzilla uses changes " dongsheng@627: "occasionally, so this hook has to know exactly which schema to use. At the " dongsheng@627: "moment, the only version supported is <literal>2.16</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:930 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">host</envar>: The hostname of the MySQL " dongsheng@627: "server that stores your Bugzilla data. The database must be configured to " dongsheng@627: "allow connections from whatever host you are running the <literal role=\"hook" dongsheng@627: "\">bugzilla</literal> hook on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:937 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">user</envar>: The username with which to " dongsheng@627: "connect to the MySQL server. The database must be configured to allow this " dongsheng@627: "user to connect from whatever host you are running the <literal role=\"hook" dongsheng@627: "\">bugzilla</literal> hook on. This user must be able to access and modify " dongsheng@627: "Bugzilla tables. The default value of this item is <literal>bugs</literal>, " dongsheng@627: "which is the standard name of the Bugzilla user in a MySQL database." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:948 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">password</envar>: The MySQL password for the " dongsheng@627: "user you configured above. This is stored as plain text, so you should make " dongsheng@627: "sure that unauthorised users cannot read the <filename role=\"special\"> /." dongsheng@627: "hgrc</filename>\\ file where you store this information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:957 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">db</envar>: The name of the Bugzilla " dongsheng@627: "database on the MySQL server. The default value of this item is " dongsheng@627: "<literal>bugs</literal>, which is the standard name of the MySQL database " dongsheng@627: "where Bugzilla stores its data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:964 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">notify</envar>: If you want Bugzilla to send " dongsheng@627: "out a notification email to subscribers after this hook has added a comment " dongsheng@627: "to a bug, you will need this hook to run a command whenever it updates the " dongsheng@627: "database. The command to run depends on where you have installed Bugzilla, " dongsheng@627: "but it will typically look something like this, if you have Bugzilla " dongsheng@627: "installed in <filename class=\"directory\">/var/www/html/bugzilla</filename>:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:977 dongsheng@627: msgid "" dongsheng@627: "The Bugzilla <literal>processmail</literal> program expects to be given a bug " dongsheng@627: "ID (the hook replaces <quote><literal>%s</literal></quote> with the bug ID) " dongsheng@627: "and an email address. It also expects to be able to write to some files in " dongsheng@627: "the directory that it runs in. If Bugzilla and this hook are not installed " dongsheng@627: "on the same machine, you will need to find a way to run <literal>processmail</" dongsheng@627: "literal> on the server where Bugzilla is installed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:992 dongsheng@627: msgid "Mapping committer names to Bugzilla user names" dongsheng@635: msgstr "提交者的名称与 Bugzilla 用户名称的映射" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:994 dongsheng@627: msgid "" dongsheng@627: "By default, the <literal role=\"hg-ext\">bugzilla</literal> hook tries to use " dongsheng@627: "the email address of a changeset's committer as the Bugzilla user name with " dongsheng@627: "which to update a bug. If this does not suit your needs, you can map " dongsheng@627: "committer email addresses to Bugzilla user names using a <literal role=\"rc-" dongsheng@627: "usermap\">usermap</literal> section." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1003 dongsheng@627: msgid "" dongsheng@627: "Each item in the <literal role=\"rc-usermap\">usermap</literal> section " dongsheng@627: "contains an email address on the left, and a Bugzilla user name on the right." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1010 dongsheng@627: msgid "" dongsheng@627: "You can either keep the <literal role=\"rc-usermap\">usermap</literal> data " dongsheng@627: "in a normal <filename role=\"special\">~/.hgrc</filename>, or tell the " dongsheng@627: "<literal role=\"hg-ext\">bugzilla</literal> hook to read the information from " dongsheng@627: "an external <filename>usermap</filename> file. In the latter case, you can " dongsheng@627: "store <filename>usermap</filename> data by itself in (for example) a user-" dongsheng@627: "modifiable repository. This makes it possible to let your users maintain " dongsheng@627: "their own <envar role=\"rc-item-bugzilla\">usermap</envar> entries. The main " dongsheng@627: "<filename role=\"special\"> /.hgrc</filename>\\ file might look like this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1026 dongsheng@627: msgid "" dongsheng@627: "While the <filename>usermap</filename> file that it refers to might look like " dongsheng@627: "this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:1035 dongsheng@627: msgid "Configuring the text that gets added to a bug" dongsheng@635: msgstr "配置增加到问题中的正文" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1037 dongsheng@627: msgid "" dongsheng@627: "You can configure the text that this hook adds as a comment; you specify it " dongsheng@627: "in the form of a Mercurial template. Several <filename role=\"special\"> /." dongsheng@627: "hgrc</filename>\\ entries (still in the <literal role=\"rc-bugzilla" dongsheng@627: "\">bugzilla</literal> section) control this behaviour." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1044 dongsheng@627: msgid "" dongsheng@627: "<literal>strip</literal>: The number of leading path elements to strip from a " dongsheng@627: "repository's path name to construct a partial path for a URL. For example, if " dongsheng@627: "the repositories on your server live under <filename class=\"directory\">/" dongsheng@627: "home/hg/repos</filename>, and you have a repository whose path is <filename " dongsheng@627: "class=\"directory\">/home/hg/repos/app/tests</filename>, then setting " dongsheng@627: "<literal>strip</literal> to <literal>4</literal> will give a partial path of " dongsheng@627: "<filename class=\"directory\">app/tests</filename>. The hook will make this " dongsheng@627: "partial path available when expanding a template, as <literal>webroot</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1058 dongsheng@627: msgid "" dongsheng@627: "<literal>template</literal>: The text of the template to use. In addition to " dongsheng@627: "the usual changeset-related variables, this template can use <literal>hgweb</" dongsheng@627: "literal> (the value of the <literal>hgweb</literal> configuration item above) " dongsheng@627: "and <literal>webroot</literal> (the path constructed using <literal>strip</" dongsheng@627: "literal> above)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1068 dongsheng@627: msgid "" dongsheng@627: "In addition, you can add a <envar role=\"rc-item-web\">baseurl</envar> item " dongsheng@627: "to the <literal role=\"rc-web\">web</literal> section of your <filename role=" dongsheng@627: "\"special\"> /.hgrc</filename>. The <literal role=\"hg-ext\">bugzilla</" dongsheng@627: "literal> hook will make this available when expanding a template, as the base " dongsheng@627: "string to use when constructing a URL that will let users browse from a " dongsheng@627: "Bugzilla comment to view a changeset. Example:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1080 dongsheng@627: msgid "" dongsheng@627: "Here is an example set of <literal role=\"hg-ext\">bugzilla</literal> hook " dongsheng@627: "config information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1097 dongsheng@627: msgid "" dongsheng@627: "The most common problems with configuring the <literal role=\"hg-ext" dongsheng@627: "\">bugzilla</literal> hook relate to running Bugzilla's " dongsheng@627: "<filename>processmail</filename> script and mapping committer names to user " dongsheng@627: "names." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1103 dongsheng@627: msgid "" dongsheng@627: "Recall from section <xref linkend=\"sec.hook.bugzilla.config\"/> above that " dongsheng@627: "the user that runs the Mercurial process on the server is also the one that " dongsheng@627: "will run the <filename>processmail</filename> script. The " dongsheng@627: "<filename>processmail</filename> script sometimes causes Bugzilla to write to " dongsheng@627: "files in its configuration directory, and Bugzilla's configuration files are " dongsheng@627: "usually owned by the user that your web server runs under." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1114 dongsheng@627: msgid "" dongsheng@627: "You can cause <filename>processmail</filename> to be run with the suitable " dongsheng@627: "user's identity using the <command>sudo</command> command. Here is an " dongsheng@627: "example entry for a <filename>sudoers</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1122 dongsheng@627: msgid "" dongsheng@627: "This allows the <literal>hg_user</literal> user to run a " dongsheng@627: "<filename>processmail-wrapper</filename> program under the identity of " dongsheng@627: "<literal>httpd_user</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1127 dongsheng@627: msgid "" dongsheng@627: "This indirection through a wrapper script is necessary, because " dongsheng@627: "<filename>processmail</filename> expects to be run with its current directory " dongsheng@627: "set to wherever you installed Bugzilla; you can't specify that kind of " dongsheng@627: "constraint in a <filename>sudoers</filename> file. The contents of the " dongsheng@627: "wrapper script are simple:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1136 dongsheng@627: msgid "" dongsheng@627: "It doesn't seem to matter what email address you pass to " dongsheng@627: "<filename>processmail</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1140 dongsheng@627: msgid "" dongsheng@627: "If your <literal role=\"rc-usermap\">usermap</literal> is not set up " dongsheng@627: "correctly, users will see an error message from the <literal role=\"hg-ext" dongsheng@627: "\">bugzilla</literal> hook when they push changes to the server. The error " dongsheng@627: "message will look like this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1148 dongsheng@627: msgid "" dongsheng@627: "What this means is that the committer's address, <literal>john.q." dongsheng@627: "public@example.com</literal>, is not a valid Bugzilla user name, nor does it " dongsheng@627: "have an entry in your <literal role=\"rc-usermap\">usermap</literal> that " dongsheng@627: "maps it to a valid Bugzilla user name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1158 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hg-ext\">notify</literal>&emdash;send email notifications" dongsheng@635: msgstr "<literal role=\"hg-ext\">notify</literal>&emdash;邮件通知" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1161 dongsheng@627: msgid "" dongsheng@627: "Although Mercurial's built-in web server provides RSS feeds of changes in " dongsheng@627: "every repository, many people prefer to receive change notifications via " dongsheng@627: "email. The <literal role=\"hg-ext\">notify</literal> hook lets you send out " dongsheng@627: "notifications to a set of email addresses whenever changesets arrive that " dongsheng@627: "those subscribers are interested in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1169 dongsheng@627: msgid "" dongsheng@627: "As with the <literal role=\"hg-ext\">bugzilla</literal> hook, the <literal " dongsheng@627: "role=\"hg-ext\">notify</literal> hook is template-driven, so you can " dongsheng@627: "customise the contents of the notification messages that it sends." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1175 dongsheng@627: msgid "" dongsheng@627: "By default, the <literal role=\"hg-ext\">notify</literal> hook includes a " dongsheng@627: "diff of every changeset that it sends out; you can limit the size of the " dongsheng@627: "diff, or turn this feature off entirely. It is useful for letting " dongsheng@627: "subscribers review changes immediately, rather than clicking to follow a URL." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:1183 dongsheng@627: msgid "Configuring the <literal role=\"hg-ext\">notify</literal> hook" dongsheng@635: msgstr "配置 <literal role=\"hg-ext\">notify</literal> 钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1186 dongsheng@627: msgid "" dongsheng@627: "You can set up the <literal role=\"hg-ext\">notify</literal> hook to send one " dongsheng@627: "email message per incoming changeset, or one per incoming group of changesets " dongsheng@627: "(all those that arrived in a single pull or push)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1197 dongsheng@627: msgid "" dongsheng@627: "Configuration information for this hook lives in the <literal role=\"rc-notify" dongsheng@627: "\">notify</literal> section of a <filename role=\"special\"> /.hgrc</filename>" dongsheng@627: "\\ file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1202 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">test</envar>: By default, this hook does not " dongsheng@627: "send out email at all; instead, it prints the message that it " dongsheng@627: "<emphasis>would</emphasis> send. Set this item to <literal>false</literal> " dongsheng@627: "to allow email to be sent. The reason that sending of email is turned off by " dongsheng@627: "default is that it takes several tries to configure this extension exactly as " dongsheng@627: "you would like, and it would be bad form to spam subscribers with a number of " dongsheng@627: "<quote>broken</quote> notifications while you debug your configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1214 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">config</envar>: The path to a configuration " dongsheng@627: "file that contains subscription information. This is kept separate from the " dongsheng@627: "main <filename role=\"special\"> /.hgrc</filename>\\ so that you can maintain " dongsheng@627: "it in a repository of its own. People can then clone that repository, update " dongsheng@627: "their subscriptions, and push the changes back to your server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1223 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">strip</envar>: The number of leading path " dongsheng@627: "separator characters to strip from a repository's path, when deciding whether " dongsheng@627: "a repository has subscribers. For example, if the repositories on your " dongsheng@627: "server live in <filename class=\"directory\">/home/hg/repos</filename>, and " dongsheng@627: "<literal role=\"hg-ext\">notify</literal> is considering a repository named " dongsheng@627: "<filename class=\"directory\">/home/hg/repos/shared/test</filename>, setting " dongsheng@627: "<envar role=\"rc-item-notify\">strip</envar> to <literal>4</literal> will " dongsheng@627: "cause <literal role=\"hg-ext\">notify</literal> to trim the path it considers " dongsheng@627: "down to <filename class=\"directory\">shared/test</filename>, and it will " dongsheng@627: "match subscribers against that." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1240 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">template</envar>: The template text to use " dongsheng@627: "when sending messages. This specifies both the contents of the message " dongsheng@627: "header and its body." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1246 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">maxdiff</envar>: The maximum number of lines " dongsheng@627: "of diff data to append to the end of a message. If a diff is longer than " dongsheng@627: "this, it is truncated. By default, this is set to 300. Set this to " dongsheng@627: "<literal>0</literal> to omit diffs from notification emails." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1255 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">sources</envar>: A list of sources of " dongsheng@627: "changesets to consider. This lets you limit <literal role=\"hg-ext\">notify</" dongsheng@627: "literal> to only sending out email about changes that remote users pushed " dongsheng@627: "into this repository via a server, for example. See section <xref linkend=" dongsheng@627: "\"sec.hook.sources\"/> for the sources you can specify here." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1267 dongsheng@627: msgid "" dongsheng@627: "If you set the <envar role=\"rc-item-web\">baseurl</envar> item in the " dongsheng@627: "<literal role=\"rc-web\">web</literal> section, you can use it in a template; " dongsheng@627: "it will be available as <literal>webroot</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1273 dongsheng@627: msgid "" dongsheng@627: "Here is an example set of <literal role=\"hg-ext\">notify</literal> " dongsheng@627: "configuration information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1289 dongsheng@627: msgid "This will produce a message that looks like the following:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1310 dongsheng@627: msgid "" dongsheng@627: "Do not forget that by default, the <literal role=\"hg-ext\">notify</literal> " dongsheng@627: "extension <emphasis>will not send any mail</emphasis> until you explicitly " dongsheng@627: "configure it to do so, by setting <envar role=\"rc-item-notify\">test</envar> " dongsheng@627: "to <literal>false</literal>. Until you do that, it simply prints the message " dongsheng@627: "it <emphasis>would</emphasis> send." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:1322 dongsheng@627: msgid "Information for writers of hooks" dongsheng@635: msgstr "编写钩子的信息" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1325 dongsheng@627: msgid "In-process hook execution" dongsheng@635: msgstr "进程内钩子的执行" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1327 dongsheng@627: msgid "An in-process hook is called with arguments of the following form:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1333 dongsheng@627: msgid "" dongsheng@627: "The <literal>ui</literal> parameter is a <literal role=\"py-mod-mercurial.ui" dongsheng@627: "\">ui</literal> object. The <literal>repo</literal> parameter is a <literal " dongsheng@627: "role=\"py-mod-mercurial.localrepo\">localrepository</literal> object. The " dongsheng@627: "names and values of the <literal>**kwargs</literal> parameters depend on the " dongsheng@627: "hook being invoked, with the following common features:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1342 dongsheng@627: msgid "" dongsheng@627: "If a parameter is named <literal>node</literal> or <literal>parentN</" dongsheng@627: "literal>, it will contain a hexadecimal changeset ID. The empty string is " dongsheng@627: "used to represent <quote>null changeset ID</quote> instead of a string of " dongsheng@627: "zeroes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1349 dongsheng@627: msgid "" dongsheng@627: "If a parameter is named <literal>url</literal>, it will contain the URL of a " dongsheng@627: "remote repository, if that can be determined." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1354 dongsheng@627: msgid "" dongsheng@627: "Boolean-valued parameters are represented as Python <literal>bool</literal> " dongsheng@627: "objects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1359 dongsheng@627: msgid "" dongsheng@627: "An in-process hook is called without a change to the process's working " dongsheng@627: "directory (unlike external hooks, which are run in the root of the " dongsheng@627: "repository). It must not change the process's working directory, or it will " dongsheng@627: "cause any calls it makes into the Mercurial API to fail." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1366 dongsheng@627: msgid "" dongsheng@627: "If a hook returns a boolean <quote>false</quote> value, it is considered to " dongsheng@627: "have succeeded. If it returns a boolean <quote>true</quote> value or raises " dongsheng@627: "an exception, it is considered to have failed. A useful way to think of the " dongsheng@627: "calling convention is <quote>tell me if you fail</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1373 dongsheng@627: msgid "" dongsheng@627: "Note that changeset IDs are passed into Python hooks as hexadecimal strings, " dongsheng@627: "not the binary hashes that Mercurial's APIs normally use. To convert a hash " dongsheng@627: "from hex to binary, use the \\pymodfunc{mercurial.node}{bin} function." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1381 dongsheng@627: msgid "External hook execution" dongsheng@635: msgstr "外部钩子的执行" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1383 dongsheng@627: msgid "" dongsheng@627: "An external hook is passed to the shell of the user running Mercurial. " dongsheng@627: "Features of that shell, such as variable substitution and command " dongsheng@627: "redirection, are available. The hook is run in the root directory of the " dongsheng@627: "repository (unlike in-process hooks, which are run in the same directory that " dongsheng@627: "Mercurial was run in)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1391 dongsheng@627: msgid "" dongsheng@627: "Hook parameters are passed to the hook as environment variables. Each " dongsheng@627: "environment variable's name is converted in upper case and prefixed with the " dongsheng@627: "string <quote><literal>HG_</literal></quote>. For example, if the name of a " dongsheng@627: "parameter is <quote><literal>node</literal></quote>, the name of the " dongsheng@627: "environment variable representing that parameter will be " dongsheng@627: "<quote><literal>HG_NODE</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1400 dongsheng@627: msgid "" dongsheng@627: "A boolean parameter is represented as the string <quote><literal>1</literal></" dongsheng@627: "quote> for <quote>true</quote>, <quote><literal>0</literal></quote> for " dongsheng@627: "<quote>false</quote>. If an environment variable is named <envar>HG_NODE</" dongsheng@627: "envar>, <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it contains a " dongsheng@627: "changeset ID represented as a hexadecimal string. The empty string is used " dongsheng@627: "to represent <quote>null changeset ID</quote> instead of a string of zeroes. " dongsheng@627: "If an environment variable is named <envar>HG_URL</envar>, it will contain " dongsheng@627: "the URL of a remote repository, if that can be determined." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1412 dongsheng@627: msgid "" dongsheng@627: "If a hook exits with a status of zero, it is considered to have succeeded. " dongsheng@627: "If it exits with a non-zero status, it is considered to have failed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1419 dongsheng@627: msgid "Finding out where changesets come from" dongsheng@635: msgstr "检查修改集来自何处" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1421 dongsheng@627: msgid "" dongsheng@627: "A hook that involves the transfer of changesets between a local repository " dongsheng@627: "and another may be able to find out information about the <quote>far side</" dongsheng@627: "quote>. Mercurial knows <emphasis>how</emphasis> changes are being " dongsheng@627: "transferred, and in many cases <emphasis>where</emphasis> they are being " dongsheng@627: "transferred to or from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:1430 dongsheng@627: msgid "Sources of changesets" dongsheng@635: msgstr "修改集的来源" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1432 dongsheng@627: msgid "" dongsheng@627: "Mercurial will tell a hook what means are, or were, used to transfer " dongsheng@627: "changesets between repositories. This is provided by Mercurial in a Python " dongsheng@627: "parameter named <literal>source</literal>, or an environment variable named " dongsheng@627: "<envar>HG_SOURCE</envar>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1440 dongsheng@627: msgid "" dongsheng@627: "<literal>serve</literal>: Changesets are transferred to or from a remote " dongsheng@627: "repository over http or ssh." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1445 dongsheng@627: msgid "" dongsheng@627: "<literal>pull</literal>: Changesets are being transferred via a pull from one " dongsheng@627: "repository into another." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1450 dongsheng@627: msgid "" dongsheng@627: "<literal>push</literal>: Changesets are being transferred via a push from one " dongsheng@627: "repository into another." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1455 dongsheng@627: msgid "" dongsheng@627: "<literal>bundle</literal>: Changesets are being transferred to or from a " dongsheng@627: "bundle." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:1462 dongsheng@627: msgid "Where changes are going&emdash;remote repository URLs" dongsheng@635: msgstr "修改集要到哪里&emdash;远程版本库的地址" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1465 dongsheng@627: msgid "" dongsheng@627: "When possible, Mercurial will tell a hook the location of the <quote>far " dongsheng@627: "side</quote> of an activity that transfers changeset data between " dongsheng@627: "repositories. This is provided by Mercurial in a Python parameter named " dongsheng@627: "<literal>url</literal>, or an environment variable named <envar>HG_URL</" dongsheng@627: "envar>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1473 dongsheng@627: msgid "" dongsheng@627: "This information is not always known. If a hook is invoked in a repository " dongsheng@627: "that is being served via http or ssh, Mercurial cannot tell where the remote " dongsheng@627: "repository is, but it may know where the client is connecting from. In such " dongsheng@627: "cases, the URL will take one of the following forms:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1480 dongsheng@627: msgid "" dongsheng@627: "<literal>remote:ssh:1.2.3.4</literal>&emdash;remote ssh client, at the IP " dongsheng@627: "address <literal>1.2.3.4</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1485 dongsheng@627: msgid "" dongsheng@627: "<literal>remote:http:1.2.3.4</literal>&emdash;remote http client, at the IP " dongsheng@627: "address <literal>1.2.3.4</literal>. If the client is using SSL, this will be " dongsheng@627: "of the form <literal>remote:https:1.2.3.4</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1492 dongsheng@627: msgid "Empty&emdash;no information could be discovered about the remote client." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:1501 dongsheng@627: msgid "Hook reference" dongsheng@635: msgstr "钩子参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1504 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">changegroup</literal>&emdash;after remote changesets " dongsheng@627: "added" dongsheng@635: msgstr "<literal role=\"hook\">changegroup</literal>&emdash;增加远程修改集之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1507 dongsheng@627: msgid "" dongsheng@627: "This hook is run after a group of pre-existing changesets has been added to " dongsheng@627: "the repository, for example via a <command role=\"hg-cmd\">hg pull</command> " dongsheng@627: "or <command role=\"hg-cmd\">hg unbundle</command>. This hook is run once per " dongsheng@627: "operation that added one or more changesets. This is in contrast to the " dongsheng@627: "<literal role=\"hook\">incoming</literal> hook, which is run once per " dongsheng@627: "changeset, regardless of whether the changesets arrive in a group." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1517 dongsheng@627: msgid "" dongsheng@627: "Some possible uses for this hook include kicking off an automated build or " dongsheng@627: "test of the added changesets, updating a bug database, or notifying " dongsheng@627: "subscribers that a repository contains new changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1523 ../en/ch10-hook.xml:1564 ../en/ch10-hook.xml:1607 dongsheng@627: #: ../en/ch10-hook.xml:1649 ../en/ch10-hook.xml:1704 ../en/ch10-hook.xml:1744 dongsheng@627: #: ../en/ch10-hook.xml:1780 ../en/ch10-hook.xml:1815 ../en/ch10-hook.xml:1877 dongsheng@627: #: ../en/ch10-hook.xml:1935 ../en/ch10-hook.xml:1969 ../en/ch10-hook.xml:1997 dongsheng@627: msgid "Parameters to this hook:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1526 ../en/ch10-hook.xml:1880 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The changeset ID of the first " dongsheng@627: "changeset in the group that was added. All changesets between this and " dongsheng@627: "\\index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were " dongsheng@627: "added by a single <command role=\"hg-cmd\">hg pull</command>, <command role=" dongsheng@627: "\"hg-cmd\">hg push</command> or <command role=\"hg-cmd\">hg unbundle</" dongsheng@627: "command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1536 ../en/ch10-hook.xml:1614 ../en/ch10-hook.xml:1707 dongsheng@627: #: ../en/ch10-hook.xml:1890 dongsheng@627: msgid "" dongsheng@627: "<literal>source</literal>: A string. The source of these changes. See " dongsheng@627: "section <xref linkend=\"sec.hook.sources\"/> for details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1541 ../en/ch10-hook.xml:1619 ../en/ch10-hook.xml:1670 dongsheng@627: #: ../en/ch10-hook.xml:1712 ../en/ch10-hook.xml:1794 ../en/ch10-hook.xml:1895 dongsheng@627: msgid "" dongsheng@627: "<literal>url</literal>: A URL. The location of the remote repository, if " dongsheng@627: "known. See section <xref linkend=\"sec.hook.url\"/> for more information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1548 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">incoming</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.incoming\"/>), <literal role=\"hook\">prechangegroup</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.prechangegroup\"/>), <literal role=\"hook" dongsheng@627: "\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook." dongsheng@627: "pretxnchangegroup\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1558 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">commit</literal>&emdash;after a new changeset is " dongsheng@627: "created" dongsheng@635: msgstr "<literal role=\"hook\">commit</literal>&emdash;创建新修改集之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1561 dongsheng@627: msgid "This hook is run after a new changeset has been created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1567 ../en/ch10-hook.xml:1938 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The changeset ID of the newly " dongsheng@627: "committed changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1571 ../en/ch10-hook.xml:1942 dongsheng@627: msgid "" dongsheng@627: "<literal>parent1</literal>: A changeset ID. The changeset ID of the first " dongsheng@627: "parent of the newly committed changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1576 ../en/ch10-hook.xml:1947 dongsheng@627: msgid "" dongsheng@627: "<literal>parent2</literal>: A changeset ID. The changeset ID of the second " dongsheng@627: "parent of the newly committed changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1582 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">precommit</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.precommit\"/>), <literal role=\"hook\">pretxncommit</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.pretxncommit\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1590 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">incoming</literal>&emdash;after one remote changeset " dongsheng@627: "is added" dongsheng@635: msgstr "<literal role=\"hook\">incoming</literal>&emdash;增加远程修改集之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1593 dongsheng@627: msgid "" dongsheng@627: "This hook is run after a pre-existing changeset has been added to the " dongsheng@627: "repository, for example via a <command role=\"hg-cmd\">hg push</command>. If " dongsheng@627: "a group of changesets was added in a single operation, this hook is called " dongsheng@627: "once for each added changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1600 dongsheng@627: msgid "" dongsheng@627: "You can use this hook for the same purposes as the <literal role=\"hook" dongsheng@627: "\">changegroup</literal> hook (section <xref linkend=\"sec.hook.changegroup\"/" dongsheng@627: ">); it's simply more convenient sometimes to run a hook once per group of " dongsheng@627: "changesets, while other times it's handier once per changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1610 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The ID of the newly added changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1626 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.changegroup\"/>) <literal role=\"hook\">prechangegroup</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.prechangegroup\"/>), <literal role=\"hook" dongsheng@627: "\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook." dongsheng@627: "pretxnchangegroup\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1636 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">outgoing</literal>&emdash;after changesets are " dongsheng@627: "propagated" dongsheng@635: msgstr "<literal role=\"hook\">outgoing</literal>&emdash;传播修改集之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1639 dongsheng@627: msgid "" dongsheng@627: "This hook is run after a group of changesets has been propagated out of this " dongsheng@627: "repository, for example by a <command role=\"hg-cmd\">hg push</command> or " dongsheng@627: "<command role=\"hg-cmd\">hg bundle</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1645 dongsheng@627: msgid "" dongsheng@627: "One possible use for this hook is to notify administrators that changes have " dongsheng@627: "been pulled." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1652 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The changeset ID of the first " dongsheng@627: "changeset of the group that was sent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1657 dongsheng@627: msgid "" dongsheng@627: "<literal>source</literal>: A string. The source of the of the operation (see " dongsheng@627: "section <xref linkend=\"sec.hook.sources\"/>). If a remote client pulled " dongsheng@627: "changes from this repository, <literal>source</literal> will be " dongsheng@627: "<literal>serve</literal>. If the client that obtained changes from this " dongsheng@627: "repository was local, <literal>source</literal> will be <literal>bundle</" dongsheng@627: "literal>, <literal>pull</literal>, or <literal>push</literal>, depending on " dongsheng@627: "the operation the client performed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1677 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">preoutgoing</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.preoutgoing\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1683 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">prechangegroup</literal>&emdash;before starting to add " dongsheng@627: "remote changesets" dongsheng@627: msgstr "" dongsheng@635: "<literal role=\"hook\">prechangegroup</literal>&emdash;增加远程修改集之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1687 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before Mercurial begins to add a group of " dongsheng@627: "changesets from another repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1691 dongsheng@627: msgid "" dongsheng@627: "This hook does not have any information about the changesets to be added, " dongsheng@627: "because it is run before transmission of those changesets is allowed to " dongsheng@627: "begin. If this hook fails, the changesets will not be transmitted." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1697 dongsheng@627: msgid "" dongsheng@627: "One use for this hook is to prevent external changes from being added to a " dongsheng@627: "repository. For example, you could use this to <quote>freeze</quote> a " dongsheng@627: "server-hosted branch temporarily or permanently so that users cannot push to " dongsheng@627: "it, while still allowing a local administrator to modify the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1719 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.changegroup\"/>), <literal role=\"hook\">incoming</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.incoming\"/>), , <literal role=\"hook" dongsheng@627: "\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook." dongsheng@627: "pretxnchangegroup\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1729 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">precommit</literal>&emdash;before starting to commit a " dongsheng@627: "changeset" dongsheng@635: msgstr "<literal role=\"hook\">precommit</literal>&emdash;提交修改集之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1732 dongsheng@627: msgid "" dongsheng@627: "This hook is run before Mercurial begins to commit a new changeset. It is run " dongsheng@627: "before Mercurial has any of the metadata for the commit, such as the files to " dongsheng@627: "be committed, the commit message, or the commit date." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1738 dongsheng@627: msgid "" dongsheng@627: "One use for this hook is to disable the ability to commit new changesets, " dongsheng@627: "while still allowing incoming changesets. Another is to run a build or test, " dongsheng@627: "and only allow the commit to begin if the build or test succeeds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1747 dongsheng@627: msgid "" dongsheng@627: "<literal>parent1</literal>: A changeset ID. The changeset ID of the first " dongsheng@627: "parent of the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1752 dongsheng@627: msgid "" dongsheng@627: "<literal>parent2</literal>: A changeset ID. The changeset ID of the second " dongsheng@627: "parent of the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1757 dongsheng@627: msgid "" dongsheng@627: "If the commit proceeds, the parents of the working directory will become the " dongsheng@627: "parents of the new changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1761 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">commit</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.commit\"/>), <literal role=\"hook\">pretxncommit</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.pretxncommit\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1769 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">preoutgoing</literal>&emdash;before starting to " dongsheng@627: "propagate changesets" dongsheng@635: msgstr "<literal role=\"hook\">preoutgoing</literal>&emdash;传播修改集之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1772 dongsheng@627: msgid "" dongsheng@627: "This hook is invoked before Mercurial knows the identities of the changesets " dongsheng@627: "to be transmitted." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1776 dongsheng@627: msgid "" dongsheng@627: "One use for this hook is to prevent changes from being transmitted to another " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1783 dongsheng@627: msgid "" dongsheng@627: "<literal>source</literal>: A string. The source of the operation that is " dongsheng@627: "attempting to obtain changes from this repository (see section <xref linkend=" dongsheng@627: "\"sec.hook.sources\"/>). See the documentation for the <literal>source</" dongsheng@627: "literal> parameter to the <literal role=\"hook\">outgoing</literal> hook, in " dongsheng@627: "section <xref linkend=\"sec.hook.outgoing\"/>, for possible values of this " dongsheng@627: "parameter." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1801 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">outgoing</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.outgoing\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1807 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretag</literal>&emdash;before tagging a changeset" dongsheng@635: msgstr "<literal role=\"hook\">pretag</literal>&emdash;创建标签之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1810 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before a tag is created. If the hook succeeds, " dongsheng@627: "creation of the tag proceeds. If the hook fails, the tag is not created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1818 dongsheng@627: msgid "" dongsheng@627: "<literal>local</literal>: A boolean. Whether the tag is local to this " dongsheng@627: "repository instance (i.e. stored in <filename role=\"special\">.hg/localtags</" dongsheng@627: "filename>) or managed by Mercurial (stored in <filename role=\"special\">." dongsheng@627: "hgtags</filename>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1825 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The ID of the changeset to be " dongsheng@627: "tagged." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1829 dongsheng@627: msgid "<literal>tag</literal>: A string. The name of the tag to be created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1834 dongsheng@627: msgid "" dongsheng@627: "If the tag to be created is revision-controlled, the <literal role=\"hook" dongsheng@627: "\">precommit</literal> and <literal role=\"hook\">pretxncommit</literal> " dongsheng@627: "hooks (sections <xref linkend=\"sec.hook.commit\"/> and <xref linkend=\"sec." dongsheng@627: "hook.pretxncommit\"/>) will also be run." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1841 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">tag</literal> (section <xref linkend=\"sec." dongsheng@627: "hook.tag\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1846 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretxnchangegroup</literal>&emdash;before completing " dongsheng@627: "addition of remote changesets" dongsheng@627: msgstr "" dongsheng@635: "<literal role=\"hook\">pretxnchangegroup</literal>&emdash;完成增加远程修改集之" dongsheng@635: "前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1850 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before a transaction&emdash;that manages the " dongsheng@627: "addition of a group of new changesets from outside the repository&emdash;" dongsheng@627: "completes. If the hook succeeds, the transaction completes, and all of the " dongsheng@627: "changesets become permanent within this repository. If the hook fails, the " dongsheng@627: "transaction is rolled back, and the data for the changesets is erased." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1859 dongsheng@627: msgid "" dongsheng@627: "This hook can access the metadata associated with the almost-added " dongsheng@627: "changesets, but it should not do anything permanent with this data. It must " dongsheng@627: "also not modify the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1865 dongsheng@627: msgid "" dongsheng@627: "While this hook is running, if other Mercurial processes access this " dongsheng@627: "repository, they will be able to see the almost-added changesets as if they " dongsheng@627: "are permanent. This may lead to race conditions if you do not take steps to " dongsheng@627: "avoid them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1872 dongsheng@627: msgid "" dongsheng@627: "This hook can be used to automatically vet a group of changesets. If the " dongsheng@627: "hook fails, all of the changesets are <quote>rejected</quote> when the " dongsheng@627: "transaction rolls back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1902 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.changegroup\"/>), <literal role=\"hook\">incoming</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.incoming\"/>), <literal role=\"hook" dongsheng@627: "\">prechangegroup</literal> (section <xref linkend=\"sec.hook.prechangegroup" dongsheng@627: "\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1912 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretxncommit</literal>&emdash;before completing commit " dongsheng@627: "of new changeset" dongsheng@635: msgstr "<literal role=\"hook\">pretxncommit</literal>&emdash;完成提交之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1915 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before a transaction&emdash;that manages a new " dongsheng@627: "commit&emdash;completes. If the hook succeeds, the transaction completes and " dongsheng@627: "the changeset becomes permanent within this repository. If the hook fails, " dongsheng@627: "the transaction is rolled back, and the commit data is erased." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1923 dongsheng@627: msgid "" dongsheng@627: "This hook can access the metadata associated with the almost-new changeset, " dongsheng@627: "but it should not do anything permanent with this data. It must also not " dongsheng@627: "modify the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1929 dongsheng@627: msgid "" dongsheng@627: "While this hook is running, if other Mercurial processes access this " dongsheng@627: "repository, they will be able to see the almost-new changeset as if it is " dongsheng@627: "permanent. This may lead to race conditions if you do not take steps to " dongsheng@627: "avoid them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1953 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">precommit</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.precommit\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1959 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">preupdate</literal>&emdash;before updating or merging " dongsheng@627: "working directory" dongsheng@627: msgstr "" dongsheng@635: "<literal role=\"hook\">preupdate</literal>&emdash;更新或合并工作目录之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1962 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before an update or merge of the working " dongsheng@627: "directory begins. It is run only if Mercurial's normal pre-update checks " dongsheng@627: "determine that the update or merge can proceed. If the hook succeeds, the " dongsheng@627: "update or merge may proceed; if it fails, the update or merge does not start." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1972 dongsheng@627: msgid "" dongsheng@627: "<literal>parent1</literal>: A changeset ID. The ID of the parent that the " dongsheng@627: "working directory is to be updated to. If the working directory is being " dongsheng@627: "merged, it will not change this parent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1978 dongsheng@627: msgid "" dongsheng@627: "<literal>parent2</literal>: A changeset ID. Only set if the working " dongsheng@627: "directory is being merged. The ID of the revision that the working directory " dongsheng@627: "is being merged with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1985 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">update</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.update\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1991 dongsheng@627: msgid "<literal role=\"hook\">tag</literal>&emdash;after tagging a changeset" dongsheng@635: msgstr "<literal role=\"hook\">tag</literal>&emdash;创建标签之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1994 dongsheng@627: msgid "This hook is run after a tag has been created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2000 dongsheng@627: msgid "" dongsheng@627: "<literal>local</literal>: A boolean. Whether the new tag is local to this " dongsheng@627: "repository instance (i.e. stored in <filename role=\"special\">.hg/" dongsheng@627: "localtags</filename>) or managed by Mercurial (stored in <filename role=" dongsheng@627: "\"special\">.hgtags</filename>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2008 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The ID of the changeset that was " dongsheng@627: "tagged." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2012 dongsheng@627: msgid "<literal>tag</literal>: A string. The name of the tag that was created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:2017 dongsheng@627: msgid "" dongsheng@627: "If the created tag is revision-controlled, the <literal role=\"hook\">commit</" dongsheng@627: "literal> hook (section <xref linkend=\"sec.hook.commit\"/>) is run before " dongsheng@627: "this hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:2022 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">pretag</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.pretag\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:2028 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">update</literal>&emdash;after updating or merging " dongsheng@627: "working directory" dongsheng@635: msgstr "<literal role=\"hook\">update</literal>&emdash;更新或合并工作目录之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:2031 dongsheng@627: msgid "" dongsheng@627: "This hook is run after an update or merge of the working directory " dongsheng@627: "completes. Since a merge can fail (if the external <command>hgmerge</" dongsheng@627: "command> command fails to resolve conflicts in a file), this hook " dongsheng@627: "communicates whether the update or merge completed cleanly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2039 dongsheng@627: msgid "" dongsheng@627: "<literal>error</literal>: A boolean. Indicates whether the update or merge " dongsheng@627: "completed successfully." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2044 dongsheng@627: msgid "" dongsheng@627: "<literal>parent1</literal>: A changeset ID. The ID of the parent that the " dongsheng@627: "working directory was updated to. If the working directory was merged, it " dongsheng@627: "will not have changed this parent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2050 dongsheng@627: msgid "" dongsheng@627: "<literal>parent2</literal>: A changeset ID. Only set if the working " dongsheng@627: "directory was merged. The ID of the revision that the working directory was " dongsheng@627: "merged with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:2056 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">preupdate</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.preupdate\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch11-template.xml:5 dongsheng@627: msgid "Customising the output of Mercurial" dongsheng@627: msgstr "定制 Mercurial 的输出" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch11-template.xml:7 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides a powerful mechanism to let you control how it displays " dongsheng@627: "information. The mechanism is based on templates. You can use templates to " dongsheng@627: "generate specific output for a single command, or to customise the entire " dongsheng@627: "appearance of the built-in web interface." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:14 dongsheng@627: msgid "Using precanned output styles" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:16 dongsheng@627: msgid "" dongsheng@627: "Packaged with Mercurial are some output styles that you can use immediately. " dongsheng@627: "A style is simply a precanned template that someone wrote and installed " dongsheng@627: "somewhere that Mercurial can find." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:21 dongsheng@627: msgid "" dongsheng@627: "Before we take a look at Mercurial's bundled styles, let's review its normal " dongsheng@627: "output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:26 dongsheng@627: msgid "" dongsheng@627: "This is somewhat informative, but it takes up a lot of space&emdash;five " dongsheng@627: "lines of output per changeset. The <literal>compact</literal> style reduces " dongsheng@627: "this to three lines, presented in a sparse manner." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:33 dongsheng@627: msgid "" dongsheng@627: "The <literal>changelog</literal> style hints at the expressive power of " dongsheng@627: "Mercurial's templating engine. This style attempts to follow the GNU " dongsheng@627: "Project's changelog guidelines<citation>web:changelog</citation>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:40 dongsheng@627: msgid "" dongsheng@627: "You will not be shocked to learn that Mercurial's default output style is " dongsheng@627: "named <literal>default</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:44 dongsheng@627: msgid "Setting a default style" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:46 dongsheng@627: msgid "" dongsheng@627: "You can modify the output style that Mercurial will use for every command by " dongsheng@627: "editing your <filename role=\"special\"> /.hgrc</filename>\\ file, naming the " dongsheng@627: "style you would prefer to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:53 dongsheng@627: msgid "" dongsheng@627: "If you write a style of your own, you can use it by either providing the path " dongsheng@627: "to your style file, or copying your style file into a location where " dongsheng@627: "Mercurial can find it (typically the <literal>templates</literal> " dongsheng@627: "subdirectory of your Mercurial install directory)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:62 dongsheng@627: msgid "Commands that support styles and templates" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:64 dongsheng@627: msgid "" dongsheng@627: "All of Mercurial's <quote><literal>log</literal>-like</quote> commands let " dongsheng@627: "you use styles and templates: <command role=\"hg-cmd\">hg incoming</command>, " dongsheng@627: "<command role=\"hg-cmd\">hg log</command>, <command role=\"hg-cmd\">hg " dongsheng@627: "outgoing</command>, and <command role=\"hg-cmd\">hg tip</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:71 dongsheng@627: msgid "" dongsheng@627: "As I write this manual, these are so far the only commands that support " dongsheng@627: "styles and templates. Since these are the most important commands that need " dongsheng@627: "customisable output, there has been little pressure from the Mercurial user " dongsheng@627: "community to add style and template support to other commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:79 dongsheng@627: msgid "The basics of templating" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:81 dongsheng@627: msgid "" dongsheng@627: "At its simplest, a Mercurial template is a piece of text. Some of the text " dongsheng@627: "never changes, while other parts are <emphasis>expanded</emphasis>, or " dongsheng@627: "replaced with new text, when necessary." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:86 dongsheng@627: msgid "" dongsheng@627: "Before we continue, let's look again at a simple example of Mercurial's " dongsheng@627: "normal output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:91 dongsheng@627: msgid "" dongsheng@627: "Now, let's run the same command, but using a template to change its output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:96 dongsheng@627: msgid "" dongsheng@627: "The example above illustrates the simplest possible template; it's just a " dongsheng@627: "piece of static text, printed once for each changeset. The <option role=\"hg-" dongsheng@627: "opt-log\">--template</option> option to the <command role=\"hg-cmd\">hg log</" dongsheng@627: "command> command tells Mercurial to use the given text as the template when " dongsheng@627: "printing each changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:104 dongsheng@627: msgid "" dongsheng@627: "Notice that the template string above ends with the text <quote><literal>\\n</" dongsheng@627: "literal></quote>. This is an <emphasis>escape sequence</emphasis>, telling " dongsheng@627: "Mercurial to print a newline at the end of each template item. If you omit " dongsheng@627: "this newline, Mercurial will run each piece of output together. See section " dongsheng@627: "<xref linkend=\"sec.template.escape\"/> for more details of escape sequences." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:112 dongsheng@627: msgid "" dongsheng@627: "A template that prints a fixed string of text all the time isn't very useful; " dongsheng@627: "let's try something a bit more complex." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:118 dongsheng@627: msgid "" dongsheng@627: "As you can see, the string <quote><literal>{desc}</literal></quote> in the " dongsheng@627: "template has been replaced in the output with the description of each " dongsheng@627: "changeset. Every time Mercurial finds text enclosed in curly braces " dongsheng@627: "(<quote><literal>{</literal></quote> and <quote><literal>}</literal></" dongsheng@627: "quote>), it will try to replace the braces and text with the expansion of " dongsheng@627: "whatever is inside. To print a literal curly brace, you must escape it, as " dongsheng@627: "described in section <xref linkend=\"sec.template.escape\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:131 dongsheng@627: msgid "Common template keywords" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:133 dongsheng@627: msgid "" dongsheng@627: "You can start writing simple templates immediately using the keywords below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:137 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">author</literal>: String. The unmodified " dongsheng@627: "author of the changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:141 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">branches</literal>: String. The name of " dongsheng@627: "the branch on which the changeset was committed. Will be empty if the branch " dongsheng@627: "name was <literal>default</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:147 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">date</literal>: Date information. The " dongsheng@627: "date when the changeset was committed. This is <emphasis>not</emphasis> " dongsheng@627: "human-readable; you must pass it through a filter that will render it " dongsheng@627: "appropriately. See section <xref linkend=\"sec.template.filter\"/> for more " dongsheng@627: "information on filters. The date is expressed as a pair of numbers. The " dongsheng@627: "first number is a Unix UTC timestamp (seconds since January 1, 1970); the " dongsheng@627: "second is the offset of the committer's timezone from UTC, in seconds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:158 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">desc</literal>: String. The text of the " dongsheng@627: "changeset description." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:161 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">files</literal>: List of strings. All " dongsheng@627: "files modified, added, or removed by this changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:166 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">file_adds</literal>: List of strings. " dongsheng@627: "Files added by this changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:170 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">file_dels</literal>: List of strings. " dongsheng@627: "Files removed by this changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:174 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">node</literal>: String. The changeset " dongsheng@627: "identification hash, as a 40-character hexadecimal string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:178 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">parents</literal>: List of strings. The " dongsheng@627: "parents of the changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:182 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">rev</literal>: Integer. The repository-" dongsheng@627: "local changeset revision number." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:186 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">tags</literal>: List of strings. Any tags " dongsheng@627: "associated with the changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:191 dongsheng@627: msgid "" dongsheng@627: "A few simple experiments will show us what to expect when we use these " dongsheng@627: "keywords; you can see the results below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:196 dongsheng@627: msgid "" dongsheng@627: "As we noted above, the date keyword does not produce human-readable output, " dongsheng@627: "so we must treat it specially. This involves using a <emphasis>filter</" dongsheng@627: "emphasis>, about which more in section <xref linkend=\"sec.template.filter\"/" dongsheng@627: ">." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:206 dongsheng@627: msgid "Escape sequences" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:208 dongsheng@627: msgid "" dongsheng@627: "Mercurial's templating engine recognises the most commonly used escape " dongsheng@627: "sequences in strings. When it sees a backslash (<quote><literal>\\</" dongsheng@627: "literal></quote>) character, it looks at the following character and " dongsheng@627: "substitutes the two characters with a single replacement, as described below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:215 dongsheng@627: msgid "" dongsheng@627: "<literal>\\textbackslash\\textbackslash</literal>: Backslash, <quote><literal>" dongsheng@627: "\\</literal></quote>, ASCII 134." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:219 dongsheng@627: msgid "<literal>\\textbackslash n</literal>: Newline, ASCII 12." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:222 dongsheng@627: msgid "<literal>\\textbackslash r</literal>: Carriage return, ASCII 15." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:225 dongsheng@627: msgid "<literal>\\textbackslash t</literal>: Tab, ASCII 11." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:228 dongsheng@627: msgid "<literal>\\textbackslash v</literal>: Vertical tab, ASCII 13." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:231 dongsheng@627: msgid "" dongsheng@627: "<literal>\\textbackslash {</literal>: Open curly brace, <quote><literal>{</" dongsheng@627: "literal></quote>, ASCII 173." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:235 dongsheng@627: msgid "" dongsheng@627: "<literal>\\textbackslash }</literal>: Close curly brace, <quote><literal>}</" dongsheng@627: "literal></quote>, ASCII 175." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:240 dongsheng@627: msgid "" dongsheng@627: "As indicated above, if you want the expansion of a template to contain a " dongsheng@627: "literal <quote><literal>\\</literal></quote>, <quote><literal>{</literal></" dongsheng@627: "quote>, or <quote><literal>{</literal></quote> character, you must escape it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:248 dongsheng@627: msgid "Filtering keywords to change their results" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:250 dongsheng@627: msgid "" dongsheng@627: "Some of the results of template expansion are not immediately easy to use. " dongsheng@627: "Mercurial lets you specify an optional chain of <emphasis>filters</emphasis> " dongsheng@627: "to modify the result of expanding a keyword. You have already seen a common " dongsheng@627: "filter, <literal role=\"template-kw-filt-date\">isodate</literal>, in action " dongsheng@627: "above, to make a date readable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:257 dongsheng@627: msgid "" dongsheng@627: "Below is a list of the most commonly used filters that Mercurial supports. " dongsheng@627: "While some filters can be applied to any text, others can only be used in " dongsheng@627: "specific circumstances. The name of each filter is followed first by an " dongsheng@627: "indication of where it can be used, then a description of its effect." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:264 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">addbreaks</literal>: Any text. Add an XHTML " dongsheng@627: "<quote><literal><br/></literal></quote> tag before the end of every " dongsheng@627: "line except the last. For example, <quote><literal>foo\\nbar</literal></" dongsheng@627: "quote> becomes <quote><literal>foo<br/>\\nbar</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:271 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">age</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render the age of the date, " dongsheng@627: "relative to the current time. Yields a string like <quote><literal>10 " dongsheng@627: "minutes</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:278 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">basename</literal>: Any text, but most " dongsheng@627: "useful for the <literal role=\"template-keyword\">files</literal> keyword and " dongsheng@627: "its relatives. Treat the text as a path, and return the basename. For " dongsheng@627: "example, <quote><literal>foo/bar/baz</literal></quote> becomes " dongsheng@627: "<quote><literal>baz</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:287 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">date</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render a date in a similar " dongsheng@627: "format to the Unix <literal role=\"template-keyword\">date</literal> command, " dongsheng@627: "but with timezone included. Yields a string like <quote><literal>Mon Sep 04 " dongsheng@627: "15:13:13 2006 -0700</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:295 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-author\">domain</literal>: Any text, but " dongsheng@627: "most useful for the <literal role=\"template-keyword\">author</literal> " dongsheng@627: "keyword. Finds the first string that looks like an email address, and " dongsheng@627: "extract just the domain component. For example, <quote><literal>Bryan " dongsheng@627: "O'Sullivan <bos@serpentine.com></literal></quote> becomes " dongsheng@627: "<quote><literal>serpentine.com</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:305 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-author\">email</literal>: Any text, but most " dongsheng@627: "useful for the <literal role=\"template-keyword\">author</literal> keyword. " dongsheng@627: "Extract the first string that looks like an email address. For example, " dongsheng@627: "<quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> " dongsheng@627: "becomes <quote><literal>bos@serpentine.com</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:314 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">escape</literal>: Any text. Replace the " dongsheng@627: "special XML/XHTML characters <quote><literal>&</literal></quote>, " dongsheng@627: "<quote><literal><</literal></quote> and <quote><literal>></literal></" dongsheng@627: "quote> with XML entities." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:322 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">fill68</literal>: Any text. Wrap the text " dongsheng@627: "to fit in 68 columns. This is useful before you pass text through the " dongsheng@627: "<literal role=\"template-filter\">tabindent</literal> filter, and still want " dongsheng@627: "it to fit in an 80-column fixed-font window." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:330 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">fill76</literal>: Any text. Wrap the text " dongsheng@627: "to fit in 76 columns." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:334 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">firstline</literal>: Any text. Yield the " dongsheng@627: "first line of text, without any trailing newlines." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:339 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">hgdate</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render the date as a pair of " dongsheng@627: "readable numbers. Yields a string like <quote><literal>1157407993 25200</" dongsheng@627: "literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:346 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">isodate</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render the date as a text " dongsheng@627: "string in ISO 8601 format. Yields a string like <quote><literal>2006-09-04 " dongsheng@627: "15:13:13 -0700</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:353 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">obfuscate</literal>: Any text, but most " dongsheng@627: "useful for the <literal role=\"template-keyword\">author</literal> keyword. " dongsheng@627: "Yield the input text rendered as a sequence of XML entities. This helps to " dongsheng@627: "defeat some particularly stupid screen-scraping email harvesting spambots." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:361 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-author\">person</literal>: Any text, but " dongsheng@627: "most useful for the <literal role=\"template-keyword\">author</literal> " dongsheng@627: "keyword. Yield the text before an email address. For example, " dongsheng@627: "<quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> " dongsheng@627: "becomes <quote><literal>Bryan O'Sullivan</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:370 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">rfc822date</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render a date using the same " dongsheng@627: "format used in email headers. Yields a string like <quote><literal>Mon, 04 " dongsheng@627: "Sep 2006 15:13:13 -0700</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:377 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-node\">short</literal>: Changeset hash. " dongsheng@627: "Yield the short form of a changeset hash, i.e. a 12-character hexadecimal " dongsheng@627: "string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:382 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">shortdate</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render the year, month, and day " dongsheng@627: "of the date. Yields a string like <quote><literal>2006-09-04</literal></" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:388 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">strip</literal>: Any text. Strip all " dongsheng@627: "leading and trailing whitespace from the string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:392 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">tabindent</literal>: Any text. Yield the " dongsheng@627: "text, with every line except the first starting with a tab character." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:397 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">urlescape</literal>: Any text. Escape all " dongsheng@627: "characters that are considered <quote>special</quote> by URL parsers. For " dongsheng@627: "example, <literal>foo bar</literal> becomes <literal>foo%20bar</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:404 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-author\">user</literal>: Any text, but most " dongsheng@627: "useful for the <literal role=\"template-keyword\">author</literal> keyword. " dongsheng@627: "Return the <quote>user</quote> portion of an email address. For example, " dongsheng@627: "<quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> " dongsheng@627: "becomes <quote><literal>bos</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch11-template.xml:417 dongsheng@627: msgid "" dongsheng@627: "If you try to apply a filter to a piece of data that it cannot process, " dongsheng@627: "Mercurial will fail and print a Python exception. For example, trying to run " dongsheng@627: "the output of the <literal role=\"template-keyword\">desc</literal> keyword " dongsheng@627: "into the <literal role=\"template-kw-filt-date\">isodate</literal> filter is " dongsheng@627: "not a good idea." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:426 dongsheng@627: msgid "Combining filters" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:428 dongsheng@627: msgid "" dongsheng@627: "It is easy to combine filters to yield output in the form you would like. " dongsheng@627: "The following chain of filters tidies up a description, then makes sure that " dongsheng@627: "it fits cleanly into 68 columns, then indents it by a further 8 characters " dongsheng@627: "(at least on Unix-like systems, where a tab is conventionally 8 characters " dongsheng@627: "wide)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:437 dongsheng@627: msgid "" dongsheng@627: "Note the use of <quote><literal>\\t</literal></quote> (a tab character) in " dongsheng@627: "the template to force the first line to be indented; this is necessary since " dongsheng@627: "<literal role=\"template-keyword\">tabindent</literal> indents all lines " dongsheng@627: "<emphasis>except</emphasis> the first." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:443 dongsheng@627: msgid "" dongsheng@627: "Keep in mind that the order of filters in a chain is significant. The first " dongsheng@627: "filter is applied to the result of the keyword; the second to the result of " dongsheng@627: "the first filter; and so on. For example, using <literal>fill68|tabindent</" dongsheng@627: "literal> gives very different results from <literal>tabindent|fill68</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:454 dongsheng@627: msgid "From templates to styles" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:456 dongsheng@627: msgid "" dongsheng@627: "A command line template provides a quick and simple way to format some " dongsheng@627: "output. Templates can become verbose, though, and it's useful to be able to " dongsheng@627: "give a template a name. A style file is a template with a name, stored in a " dongsheng@627: "file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:461 dongsheng@627: msgid "" dongsheng@627: "More than that, using a style file unlocks the power of Mercurial's " dongsheng@627: "templating engine in ways that are not possible using the command line " dongsheng@627: "<option role=\"hg-opt-log\">--template</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:467 dongsheng@627: msgid "The simplest of style files" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:469 dongsheng@627: msgid "Our simple style file contains just one line:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:473 dongsheng@627: msgid "" dongsheng@627: "This tells Mercurial, <quote>if you're printing a changeset, use the text on " dongsheng@627: "the right as the template</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:479 dongsheng@627: msgid "Style file syntax" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:481 dongsheng@627: msgid "The syntax rules for a style file are simple." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:484 dongsheng@627: msgid "The file is processed one line at a time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:487 dongsheng@627: msgid "Leading and trailing white space are ignored." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:490 dongsheng@627: msgid "Empty lines are skipped." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:492 dongsheng@627: msgid "" dongsheng@627: "If a line starts with either of the characters <quote><literal>#</literal></" dongsheng@627: "quote> or <quote><literal>;</literal></quote>, the entire line is treated as " dongsheng@627: "a comment, and skipped as if empty." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:497 dongsheng@627: msgid "" dongsheng@627: "A line starts with a keyword. This must start with an alphabetic character " dongsheng@627: "or underscore, and can subsequently contain any alphanumeric character or " dongsheng@627: "underscore. (In regexp notation, a keyword must match <literal>[A-Za-z_][A-" dongsheng@627: "Za-z0-9_]*</literal>.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:503 dongsheng@627: msgid "" dongsheng@627: "The next element must be an <quote><literal>=</literal></quote> character, " dongsheng@627: "which can be preceded or followed by an arbitrary amount of white space." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:508 dongsheng@627: msgid "" dongsheng@627: "If the rest of the line starts and ends with matching quote characters " dongsheng@627: "(either single or double quote), it is treated as a template body." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:512 dongsheng@627: msgid "" dongsheng@627: "If the rest of the line <emphasis>does not</emphasis> start with a quote " dongsheng@627: "character, it is treated as the name of a file; the contents of this file " dongsheng@627: "will be read and used as a template body." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:521 dongsheng@627: msgid "Style files by example" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:523 dongsheng@627: msgid "" dongsheng@627: "To illustrate how to write a style file, we will construct a few by example. " dongsheng@627: "Rather than provide a complete style file and walk through it, we'll mirror " dongsheng@627: "the usual process of developing a style file by starting with something very " dongsheng@627: "simple, and walking through a series of successively more complete examples." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:530 dongsheng@627: msgid "Identifying mistakes in style files" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:532 dongsheng@627: msgid "" dongsheng@627: "If Mercurial encounters a problem in a style file you are working on, it " dongsheng@627: "prints a terse error message that, once you figure out what it means, is " dongsheng@627: "actually quite useful." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:538 dongsheng@627: msgid "" dongsheng@627: "Notice that <filename>broken.style</filename> attempts to define a " dongsheng@627: "<literal>changeset</literal> keyword, but forgets to give any content for it. " dongsheng@627: "When instructed to use this style file, Mercurial promptly complains." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:545 dongsheng@627: msgid "This error message looks intimidating, but it is not too hard to follow." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:549 dongsheng@627: msgid "" dongsheng@627: "The first component is simply Mercurial's way of saying <quote>I am giving " dongsheng@627: "up</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:554 dongsheng@627: msgid "Next comes the name of the style file that contains the error." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:560 dongsheng@627: msgid "" dongsheng@627: "Following the file name is the line number where the error was encountered." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:565 dongsheng@627: msgid "Finally, a description of what went wrong." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:570 dongsheng@627: msgid "" dongsheng@627: "The description of the problem is not always clear (as in this case), but " dongsheng@627: "even when it is cryptic, it is almost always trivial to visually inspect the " dongsheng@627: "offending line in the style file and see what is wrong." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:578 dongsheng@627: msgid "Uniquely identifying a repository" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:580 dongsheng@627: msgid "" dongsheng@627: "If you would like to be able to identify a Mercurial repository <quote>fairly " dongsheng@627: "uniquely</quote> using a short string as an identifier, you can use the first " dongsheng@627: "revision in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:587 dongsheng@627: msgid "" dongsheng@627: "This is not guaranteed to be unique, but it is nevertheless useful in many " dongsheng@627: "cases." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:590 dongsheng@627: msgid "" dongsheng@627: "It will not work in a completely empty repository, because such a repository " dongsheng@627: "does not have a revision zero." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:594 dongsheng@627: msgid "" dongsheng@627: "Neither will it work in the (extremely rare) case where a repository is a " dongsheng@627: "merge of two or more formerly independent repositories, and you still have " dongsheng@627: "those repositories around." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:599 dongsheng@627: msgid "Here are some uses to which you could put this identifier:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:602 dongsheng@627: msgid "" dongsheng@627: "As a key into a table for a database that manages repositories on a server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:605 dongsheng@627: msgid "" dongsheng@627: "As half of a {<emphasis>repository ID</emphasis>, <emphasis>revision ID</" dongsheng@627: "emphasis>} tuple. Save this information away when you run an automated build " dongsheng@627: "or other activity, so that you can <quote>replay</quote> the build later if " dongsheng@627: "necessary." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:614 dongsheng@627: msgid "Mimicking Subversion's output" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:616 dongsheng@627: msgid "" dongsheng@627: "Let's try to emulate the default output format used by another revision " dongsheng@627: "control tool, Subversion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:621 dongsheng@627: msgid "" dongsheng@627: "Since Subversion's output style is fairly simple, it is easy to copy-and-" dongsheng@627: "paste a hunk of its output into a file, and replace the text produced above " dongsheng@627: "by Subversion with the template values we'd like to see expanded." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:628 dongsheng@627: msgid "" dongsheng@627: "There are a few small ways in which this template deviates from the output " dongsheng@627: "produced by Subversion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:631 dongsheng@627: msgid "" dongsheng@627: "Subversion prints a <quote>readable</quote> date (the <quote><literal>Wed, 27 " dongsheng@627: "Sep 2006</literal></quote> in the example output above) in parentheses. " dongsheng@627: "Mercurial's templating engine does not provide a way to display a date in " dongsheng@627: "this format without also printing the time and time zone." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:638 dongsheng@627: msgid "" dongsheng@627: "We emulate Subversion's printing of <quote>separator</quote> lines full of " dongsheng@627: "<quote><literal>-</literal></quote> characters by ending the template with " dongsheng@627: "such a line. We use the templating engine's <literal role=\"template-keyword" dongsheng@627: "\">header</literal> keyword to print a separator line as the first line of " dongsheng@627: "output (see below), thus achieving similar output to Subversion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:647 dongsheng@627: msgid "" dongsheng@627: "Subversion's output includes a count in the header of the number of lines in " dongsheng@627: "the commit message. We cannot replicate this in Mercurial; the templating " dongsheng@627: "engine does not currently provide a filter that counts the number of lines " dongsheng@627: "the template generates." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:653 dongsheng@627: msgid "" dongsheng@627: "It took me no more than a minute or two of work to replace literal text from " dongsheng@627: "an example of Subversion's output with some keywords and filters to give the " dongsheng@627: "template above. The style file simply refers to the template." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:660 dongsheng@627: msgid "" dongsheng@627: "We could have included the text of the template file directly in the style " dongsheng@627: "file by enclosing it in quotes and replacing the newlines with " dongsheng@627: "<quote><literal>\\n</literal></quote> sequences, but it would have made the " dongsheng@627: "style file too difficult to read. Readability is a good guide when you're " dongsheng@627: "trying to decide whether some text belongs in a style file, or in a template " dongsheng@627: "file that the style file points to. If the style file will look too big or " dongsheng@627: "cluttered if you insert a literal piece of text, drop it into a template " dongsheng@627: "instead." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch12-mq.xml:5 dongsheng@627: msgid "Managing change with Mercurial Queues" dongsheng@627: msgstr "使用 MQ 管理修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:8 dongsheng@627: msgid "The patch management problem" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:10 dongsheng@627: msgid "" dongsheng@627: "Here is a common scenario: you need to install a software package from " dongsheng@627: "source, but you find a bug that you must fix in the source before you can " dongsheng@627: "start using the package. You make your changes, forget about the package for " dongsheng@627: "a while, and a few months later you need to upgrade to a newer version of the " dongsheng@627: "package. If the newer version of the package still has the bug, you must " dongsheng@627: "extract your fix from the older source tree and apply it against the newer " dongsheng@627: "version. This is a tedious task, and it's easy to make mistakes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:20 dongsheng@627: msgid "" dongsheng@627: "This is a simple case of the <quote>patch management</quote> problem. You " dongsheng@627: "have an <quote>upstream</quote> source tree that you can't change; you need " dongsheng@627: "to make some local changes on top of the upstream tree; and you'd like to be " dongsheng@627: "able to keep those changes separate, so that you can apply them to newer " dongsheng@627: "versions of the upstream source." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:27 dongsheng@627: msgid "" dongsheng@627: "The patch management problem arises in many situations. Probably the most " dongsheng@627: "visible is that a user of an open source software project will contribute a " dongsheng@627: "bug fix or new feature to the project's maintainers in the form of a patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:32 dongsheng@627: msgid "" dongsheng@627: "Distributors of operating systems that include open source software often " dongsheng@627: "need to make changes to the packages they distribute so that they will build " dongsheng@627: "properly in their environments." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:37 dongsheng@627: msgid "" dongsheng@627: "When you have few changes to maintain, it is easy to manage a single patch " dongsheng@627: "using the standard <command>diff</command> and <command>patch</command> " dongsheng@627: "programs (see section <xref linkend=\"sec.mq.patch\"/> for a discussion of " dongsheng@627: "these tools). Once the number of changes grows, it starts to make sense to " dongsheng@627: "maintain patches as discrete <quote>chunks of work,</quote> so that for " dongsheng@627: "example a single patch will contain only one bug fix (the patch might modify " dongsheng@627: "several files, but it's doing <quote>only one thing</quote>), and you may " dongsheng@627: "have a number of such patches for different bugs you need fixed and local " dongsheng@627: "changes you require. In this situation, if you submit a bug fix patch to the " dongsheng@627: "upstream maintainers of a package and they include your fix in a subsequent " dongsheng@627: "release, you can simply drop that single patch when you're updating to the " dongsheng@627: "newer release." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:52 dongsheng@627: msgid "" dongsheng@627: "Maintaining a single patch against an upstream tree is a little tedious and " dongsheng@627: "error-prone, but not difficult. However, the complexity of the problem grows " dongsheng@627: "rapidly as the number of patches you have to maintain increases. With more " dongsheng@627: "than a tiny number of patches in hand, understanding which ones you have " dongsheng@627: "applied and maintaining them moves from messy to overwhelming." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:59 dongsheng@627: msgid "" dongsheng@627: "Fortunately, Mercurial includes a powerful extension, Mercurial Queues (or " dongsheng@627: "simply <quote>MQ</quote>), that massively simplifies the patch management " dongsheng@627: "problem." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:65 dongsheng@627: msgid "The prehistory of Mercurial Queues" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:67 dongsheng@627: msgid "" dongsheng@627: "During the late 1990s, several Linux kernel developers started to maintain " dongsheng@627: "<quote>patch series</quote> that modified the behaviour of the Linux kernel. " dongsheng@627: "Some of these series were focused on stability, some on feature coverage, and " dongsheng@627: "others were more speculative." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:73 dongsheng@627: msgid "" dongsheng@627: "The sizes of these patch series grew rapidly. In 2002, Andrew Morton " dongsheng@627: "published some shell scripts he had been using to automate the task of " dongsheng@627: "managing his patch queues. Andrew was successfully using these scripts to " dongsheng@627: "manage hundreds (sometimes thousands) of patches on top of the Linux kernel." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:80 dongsheng@627: msgid "A patchwork quilt" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:82 dongsheng@627: msgid "" dongsheng@627: "In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the approach " dongsheng@627: "of Andrew's scripts and published a tool called <quote>patchwork quilt</" dongsheng@627: "quote> <citation>web:quilt</citation>, or simply <quote>quilt</quote> (see " dongsheng@627: "<citation>gruenbacher:2005</citation> for a paper describing it). Because " dongsheng@627: "quilt substantially automated patch management, it rapidly gained a large " dongsheng@627: "following among open source software developers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:91 dongsheng@627: msgid "" dongsheng@627: "Quilt manages a <emphasis>stack of patches</emphasis> on top of a directory " dongsheng@627: "tree. To begin, you tell quilt to manage a directory tree, and tell it which " dongsheng@627: "files you want to manage; it stores away the names and contents of those " dongsheng@627: "files. To fix a bug, you create a new patch (using a single command), edit " dongsheng@627: "the files you need to fix, then <quote>refresh</quote> the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:99 dongsheng@627: msgid "" dongsheng@627: "The refresh step causes quilt to scan the directory tree; it updates the " dongsheng@627: "patch with all of the changes you have made. You can create another patch on " dongsheng@627: "top of the first, which will track the changes required to modify the tree " dongsheng@627: "from <quote>tree with one patch applied</quote> to <quote>tree with two " dongsheng@627: "patches applied</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:106 dongsheng@627: msgid "" dongsheng@627: "You can <emphasis>change</emphasis> which patches are applied to the tree. " dongsheng@627: "If you <quote>pop</quote> a patch, the changes made by that patch will vanish " dongsheng@627: "from the directory tree. Quilt remembers which patches you have popped, " dongsheng@627: "though, so you can <quote>push</quote> a popped patch again, and the " dongsheng@627: "directory tree will be restored to contain the modifications in the patch. " dongsheng@627: "Most importantly, you can run the <quote>refresh</quote> command at any time, " dongsheng@627: "and the topmost applied patch will be updated. This means that you can, at " dongsheng@627: "any time, change both which patches are applied and what modifications those " dongsheng@627: "patches make." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:118 dongsheng@627: msgid "" dongsheng@627: "Quilt knows nothing about revision control tools, so it works equally well on " dongsheng@627: "top of an unpacked tarball or a Subversion working copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:124 dongsheng@627: msgid "From patchwork quilt to Mercurial Queues" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:126 dongsheng@627: msgid "" dongsheng@627: "In mid-2005, Chris Mason took the features of quilt and wrote an extension " dongsheng@627: "that he called Mercurial Queues, which added quilt-like behaviour to " dongsheng@627: "Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:130 dongsheng@627: msgid "" dongsheng@627: "The key difference between quilt and MQ is that quilt knows nothing about " dongsheng@627: "revision control systems, while MQ is <emphasis>integrated</emphasis> into " dongsheng@627: "Mercurial. Each patch that you push is represented as a Mercurial " dongsheng@627: "changeset. Pop a patch, and the changeset goes away." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:136 dongsheng@627: msgid "" dongsheng@627: "Because quilt does not care about revision control tools, it is still a " dongsheng@627: "tremendously useful piece of software to know about for situations where you " dongsheng@627: "cannot use Mercurial and MQ." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:144 dongsheng@627: msgid "The huge advantage of MQ" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:146 dongsheng@627: msgid "" dongsheng@627: "I cannot overstate the value that MQ offers through the unification of " dongsheng@627: "patches and revision control." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:149 dongsheng@627: msgid "" dongsheng@627: "A major reason that patches have persisted in the free software and open " dongsheng@627: "source world&emdash;in spite of the availability of increasingly capable " dongsheng@627: "revision control tools over the years&emdash;is the <emphasis>agility</" dongsheng@627: "emphasis> they offer." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:155 dongsheng@627: msgid "" dongsheng@627: "Traditional revision control tools make a permanent, irreversible record of " dongsheng@627: "everything that you do. While this has great value, it's also somewhat " dongsheng@627: "stifling. If you want to perform a wild-eyed experiment, you have to be " dongsheng@627: "careful in how you go about it, or you risk leaving unneeded&emdash;or worse, " dongsheng@627: "misleading or destabilising&emdash;traces of your missteps and errors in the " dongsheng@627: "permanent revision record." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:163 dongsheng@627: msgid "" dongsheng@627: "By contrast, MQ's marriage of distributed revision control with patches makes " dongsheng@627: "it much easier to isolate your work. Your patches live on top of normal " dongsheng@627: "revision history, and you can make them disappear or reappear at will. If " dongsheng@627: "you don't like a patch, you can drop it. If a patch isn't quite as you want " dongsheng@627: "it to be, simply fix it&emdash;as many times as you need to, until you have " dongsheng@627: "refined it into the form you desire." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:171 dongsheng@627: msgid "" dongsheng@627: "As an example, the integration of patches with revision control makes " dongsheng@627: "understanding patches and debugging their effects&emdash;and their interplay " dongsheng@627: "with the code they're based on&emdash;<emphasis>enormously</emphasis> easier. " dongsheng@627: "Since every applied patch has an associated changeset, you can give <command " dongsheng@627: "role=\"hg-cmd\">hg log</command> a file name to see which changesets and " dongsheng@627: "patches affected the file. You can use the <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command> command to binary-search through all changesets and applied " dongsheng@627: "patches to see where a bug got introduced or fixed. You can use the <command " dongsheng@627: "role=\"hg-cmd\">hg annotate</command> command to see which changeset or patch " dongsheng@627: "modified a particular line of a source file. And so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:187 dongsheng@627: msgid "Understanding patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:189 dongsheng@627: msgid "" dongsheng@627: "Because MQ doesn't hide its patch-oriented nature, it is helpful to " dongsheng@627: "understand what patches are, and a little about the tools that work with them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:193 dongsheng@627: msgid "" dongsheng@627: "The traditional Unix <command>diff</command> command compares two files, and " dongsheng@627: "prints a list of differences between them. The <command>patch</command> " dongsheng@627: "command understands these differences as <emphasis>modifications</emphasis> " dongsheng@627: "to make to a file. Take a look below for a simple example of these commands " dongsheng@627: "in action." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:202 dongsheng@627: msgid "" dongsheng@627: "The type of file that <command>diff</command> generates (and <command>patch</" dongsheng@627: "command> takes as input) is called a <quote>patch</quote> or a <quote>diff</" dongsheng@627: "quote>; there is no difference between a patch and a diff. (We'll use the " dongsheng@627: "term <quote>patch</quote>, since it's more commonly used.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:208 dongsheng@627: msgid "" dongsheng@627: "A patch file can start with arbitrary text; the <command>patch</command> " dongsheng@627: "command ignores this text, but MQ uses it as the commit message when creating " dongsheng@627: "changesets. To find the beginning of the patch content, <command>patch</" dongsheng@627: "command> searches for the first line that starts with the string " dongsheng@627: "<quote><literal>diff -</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:215 dongsheng@627: msgid "" dongsheng@627: "MQ works with <emphasis>unified</emphasis> diffs (<command>patch</command> " dongsheng@627: "can accept several other diff formats, but MQ doesn't). A unified diff " dongsheng@627: "contains two kinds of header. The <emphasis>file header</emphasis> describes " dongsheng@627: "the file being modified; it contains the name of the file to modify. When " dongsheng@627: "<command>patch</command> sees a new file header, it looks for a file with " dongsheng@627: "that name to start modifying." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:223 dongsheng@627: msgid "" dongsheng@627: "After the file header comes a series of <emphasis>hunks</emphasis>. Each " dongsheng@627: "hunk starts with a header; this identifies the range of line numbers within " dongsheng@627: "the file that the hunk should modify. Following the header, a hunk starts " dongsheng@627: "and ends with a few (usually three) lines of text from the unmodified file; " dongsheng@627: "these are called the <emphasis>context</emphasis> for the hunk. If there's " dongsheng@627: "only a small amount of context between successive hunks, <command>diff</" dongsheng@627: "command> doesn't print a new hunk header; it just runs the hunks together, " dongsheng@627: "with a few lines of context between modifications." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:235 dongsheng@627: msgid "" dongsheng@627: "Each line of context begins with a space character. Within the hunk, a line " dongsheng@627: "that begins with <quote><literal>-</literal></quote> means <quote>remove this " dongsheng@627: "line,</quote> while a line that begins with <quote><literal>+</literal></" dongsheng@627: "quote> means <quote>insert this line.</quote> For example, a line that is " dongsheng@627: "modified is represented by one deletion and one insertion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:243 dongsheng@627: msgid "" dongsheng@627: "We will return to some of the more subtle aspects of patches later (in " dongsheng@627: "section <xref linkend=\"sec.mq.adv-patch\"/>), but you should have enough " dongsheng@627: "information now to use MQ." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:250 dongsheng@627: msgid "Getting started with Mercurial Queues" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:252 dongsheng@627: msgid "" dongsheng@627: "Because MQ is implemented as an extension, you must explicitly enable before " dongsheng@627: "you can use it. (You don't need to download anything; MQ ships with the " dongsheng@627: "standard Mercurial distribution.) To enable MQ, edit your <filename role=" dongsheng@627: "\"home\">~/.hgrc</filename> file, and add the lines below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:261 dongsheng@627: msgid "" dongsheng@627: "Once the extension is enabled, it will make a number of new commands " dongsheng@627: "available. To verify that the extension is working, you can use <command " dongsheng@627: "role=\"hg-cmd\">hg help</command> to see if the <command role=\"hg-ext-mq" dongsheng@627: "\">qinit</command> command is now available." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:269 dongsheng@627: msgid "" dongsheng@627: "You can use MQ with <emphasis>any</emphasis> Mercurial repository, and its " dongsheng@627: "commands only operate within that repository. To get started, simply prepare " dongsheng@627: "the repository using the <command role=\"hg-ext-mq\">qinit</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:276 dongsheng@627: msgid "" dongsheng@627: "This command creates an empty directory called <filename role=\"special\" " dongsheng@627: "class=\"directory\">.hg/patches</filename>, where MQ will keep its metadata. " dongsheng@627: "As with many Mercurial commands, the <command role=\"hg-ext-mq\">qinit</" dongsheng@627: "command> command prints nothing if it succeeds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:283 dongsheng@627: msgid "Creating a new patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:285 dongsheng@627: msgid "" dongsheng@627: "To begin work on a new patch, use the <command role=\"hg-ext-mq\">qnew</" dongsheng@627: "command> command. This command takes one argument, the name of the patch to " dongsheng@627: "create." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:289 dongsheng@627: msgid "" dongsheng@627: "MQ will use this as the name of an actual file in the <filename role=\"special" dongsheng@627: "\" class=\"directory\">.hg/patches</filename> directory, as you can see below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:296 dongsheng@627: msgid "" dongsheng@627: "Also newly present in the <filename role=\"special\" class=\"directory\">.hg/" dongsheng@627: "patches</filename> directory are two other files, <filename role=\"special" dongsheng@627: "\">series</filename> and <filename role=\"special\">status</filename>. The " dongsheng@627: "<filename role=\"special\">series</filename> file lists all of the patches " dongsheng@627: "that MQ knows about for this repository, with one patch per line. Mercurial " dongsheng@627: "uses the <filename role=\"special\">status</filename> file for internal book-" dongsheng@627: "keeping; it tracks all of the patches that MQ has <emphasis>applied</" dongsheng@627: "emphasis> in this repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch12-mq.xml:308 dongsheng@627: msgid "" dongsheng@627: "You may sometimes want to edit the <filename role=\"special\">series</" dongsheng@627: "filename> file by hand; for example, to change the sequence in which some " dongsheng@627: "patches are applied. However, manually editing the <filename role=\"special" dongsheng@627: "\">status</filename> file is almost always a bad idea, as it's easy to " dongsheng@627: "corrupt MQ's idea of what is happening." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:317 dongsheng@627: msgid "" dongsheng@627: "Once you have created your new patch, you can edit files in the working " dongsheng@627: "directory as you usually would. All of the normal Mercurial commands, such " dongsheng@627: "as <command role=\"hg-cmd\">hg diff</command> and <command role=\"hg-cmd\">hg " dongsheng@627: "annotate</command>, work exactly as they did before." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:325 dongsheng@627: msgid "Refreshing a patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:327 dongsheng@627: msgid "" dongsheng@627: "When you reach a point where you want to save your work, use the <command " dongsheng@627: "role=\"hg-ext-mq\">qrefresh</command> command to update the patch you are " dongsheng@627: "working on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:333 dongsheng@627: msgid "" dongsheng@627: "This command folds the changes you have made in the working directory into " dongsheng@627: "your patch, and updates its corresponding changeset to contain those changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:337 dongsheng@627: msgid "" dongsheng@627: "You can run <command role=\"hg-ext-mq\">qrefresh</command> as often as you " dongsheng@627: "like, so it's a good way to <quote>checkpoint</quote> your work. Refresh " dongsheng@627: "your patch at an opportune time; try an experiment; and if the experiment " dongsheng@627: "doesn't work out, <command role=\"hg-cmd\">hg revert</command> your " dongsheng@627: "modifications back to the last time you refreshed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:348 dongsheng@627: msgid "Stacking and tracking patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:350 dongsheng@627: msgid "" dongsheng@627: "Once you have finished working on a patch, or need to work on another, you " dongsheng@627: "can use the <command role=\"hg-ext-mq\">qnew</command> command again to " dongsheng@627: "create a new patch. Mercurial will apply this patch on top of your existing " dongsheng@627: "patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:357 dongsheng@627: msgid "" dongsheng@627: "Notice that the patch contains the changes in our prior patch as part of its " dongsheng@627: "context (you can see this more clearly in the output of <command role=\"hg-cmd" dongsheng@627: "\">hg annotate</command>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:362 dongsheng@627: msgid "" dongsheng@627: "So far, with the exception of <command role=\"hg-ext-mq\">qnew</command> and " dongsheng@627: "<command role=\"hg-ext-mq\">qrefresh</command>, we've been careful to only " dongsheng@627: "use regular Mercurial commands. However, MQ provides many commands that are " dongsheng@627: "easier to use when you are thinking about patches, as illustrated below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:372 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qseries</command> command lists every patch " dongsheng@627: "that MQ knows about in this repository, from oldest to newest (most recently " dongsheng@627: "<emphasis>created</emphasis>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:378 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qapplied</command> command lists every patch " dongsheng@627: "that MQ has <emphasis>applied</emphasis> in this repository, again from " dongsheng@627: "oldest to newest (most recently applied)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:387 dongsheng@627: msgid "Manipulating the patch stack" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:389 dongsheng@627: msgid "" dongsheng@627: "The previous discussion implied that there must be a difference between " dongsheng@627: "<quote>known</quote> and <quote>applied</quote> patches, and there is. MQ " dongsheng@627: "can manage a patch without it being applied in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:394 dongsheng@627: msgid "" dongsheng@627: "An <emphasis>applied</emphasis> patch has a corresponding changeset in the " dongsheng@627: "repository, and the effects of the patch and changeset are visible in the " dongsheng@627: "working directory. You can undo the application of a patch using the " dongsheng@627: "<command role=\"hg-ext-mq\">qpop</command> command. MQ still <emphasis>knows " dongsheng@627: "about</emphasis>, or manages, a popped patch, but the patch no longer has a " dongsheng@627: "corresponding changeset in the repository, and the working directory does not " dongsheng@627: "contain the changes made by the patch. Figure <xref linkend=\"fig.mq.stack\"/" dongsheng@627: "> illustrates the difference between applied and tracked patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch12-mq.xml:407 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/mq-stack.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch12-mq.xml:409 dongsheng@627: msgid "Applied and unapplied patches in the MQ patch stack" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:414 dongsheng@627: msgid "" dongsheng@627: "You can reapply an unapplied, or popped, patch using the <command role=\"hg-" dongsheng@627: "ext-mq\">qpush</command> command. This creates a new changeset to correspond " dongsheng@627: "to the patch, and the patch's changes once again become present in the " dongsheng@627: "working directory. See below for examples of <command role=\"hg-ext-mq" dongsheng@627: "\">qpop</command> and <command role=\"hg-ext-mq\">qpush</command> in action." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:423 dongsheng@627: msgid "" dongsheng@627: "Notice that once we have popped a patch or two patches, the output of " dongsheng@627: "<command role=\"hg-ext-mq\">qseries</command> remains the same, while that of " dongsheng@627: "<command role=\"hg-ext-mq\">qapplied</command> has changed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:431 dongsheng@627: msgid "Pushing and popping many patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:433 dongsheng@627: msgid "" dongsheng@627: "While <command role=\"hg-ext-mq\">qpush</command> and <command role=\"hg-ext-" dongsheng@627: "mq\">qpop</command> each operate on a single patch at a time by default, you " dongsheng@627: "can push and pop many patches in one go. The <option role=\"hg-ext-mq-cmd-" dongsheng@627: "qpush-opt\">hg -a</option> option to <command role=\"hg-ext-mq\">qpush</" dongsheng@627: "command> causes it to push all unapplied patches, while the <option role=\"hg-" dongsheng@627: "ext-mq-cmd-qpop-opt\">-a</option> option to <command role=\"hg-ext-mq\">qpop</" dongsheng@627: "command> causes it to pop all applied patches. (For some more ways to push " dongsheng@627: "and pop many patches, see section <xref linkend=\"sec.mq.perf\"/> below.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:450 dongsheng@627: msgid "Safety checks, and overriding them" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:452 dongsheng@627: msgid "" dongsheng@627: "Several MQ commands check the working directory before they do anything, and " dongsheng@627: "fail if they find any modifications. They do this to ensure that you won't " dongsheng@627: "lose any changes that you have made, but not yet incorporated into a patch. " dongsheng@627: "The example below illustrates this; the <command role=\"hg-ext-mq\">qnew</" dongsheng@627: "command> command will not create a new patch if there are outstanding " dongsheng@627: "changes, caused in this case by the <command role=\"hg-cmd\">hg add</command> " dongsheng@627: "of <filename>file3</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:464 dongsheng@627: msgid "" dongsheng@627: "Commands that check the working directory all take an <quote>I know what I'm " dongsheng@627: "doing</quote> option, which is always named <option>-f</option>. The exact " dongsheng@627: "meaning of <option>-f</option> depends on the command. For example, <command " dongsheng@627: "role=\"hg-cmd\">hg qnew <option role=\"hg-ext-mq-cmd-qnew-opt\">hg -f</" dongsheng@627: "option></command> will incorporate any outstanding changes into the new patch " dongsheng@627: "it creates, but <command role=\"hg-cmd\">hg qpop <option role=\"hg-ext-mq-cmd-" dongsheng@627: "qpop-opt\">hg -f</option></command> will revert modifications to any files " dongsheng@627: "affected by the patch that it is popping. Be sure to read the documentation " dongsheng@627: "for a command's <option>-f</option> option before you use it!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:479 dongsheng@627: msgid "Working on several patches at once" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:481 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qrefresh</command> command always refreshes " dongsheng@627: "the <emphasis>topmost</emphasis> applied patch. This means that you can " dongsheng@627: "suspend work on one patch (by refreshing it), pop or push to make a different " dongsheng@627: "patch the top, and work on <emphasis>that</emphasis> patch for a while." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:488 dongsheng@627: msgid "" dongsheng@627: "Here's an example that illustrates how you can use this ability. Let's say " dongsheng@627: "you're developing a new feature as two patches. The first is a change to the " dongsheng@627: "core of your software, and the second&emdash;layered on top of the " dongsheng@627: "first&emdash;changes the user interface to use the code you just added to the " dongsheng@627: "core. If you notice a bug in the core while you're working on the UI patch, " dongsheng@627: "it's easy to fix the core. Simply <command role=\"hg-ext-mq\">qrefresh</" dongsheng@627: "command> the UI patch to save your in-progress changes, and <command role=" dongsheng@627: "\"hg-ext-mq\">qpop</command> down to the core patch. Fix the core bug, " dongsheng@627: "<command role=\"hg-ext-mq\">qrefresh</command> the core patch, and <command " dongsheng@627: "role=\"hg-ext-mq\">qpush</command> back to the UI patch to continue where you " dongsheng@627: "left off." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:505 dongsheng@627: msgid "More about patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:507 dongsheng@627: msgid "" dongsheng@627: "MQ uses the GNU <command>patch</command> command to apply patches, so it's " dongsheng@627: "helpful to know a few more detailed aspects of how <command>patch</command> " dongsheng@627: "works, and about patches themselves." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:513 dongsheng@627: msgid "The strip count" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:515 dongsheng@627: msgid "" dongsheng@627: "If you look at the file headers in a patch, you will notice that the " dongsheng@627: "pathnames usually have an extra component on the front that isn't present in " dongsheng@627: "the actual path name. This is a holdover from the way that people used to " dongsheng@627: "generate patches (people still do this, but it's somewhat rare with modern " dongsheng@627: "revision control tools)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:522 dongsheng@627: msgid "" dongsheng@627: "Alice would unpack a tarball, edit her files, then decide that she wanted to " dongsheng@627: "create a patch. So she'd rename her working directory, unpack the tarball " dongsheng@627: "again (hence the need for the rename), and use the <option role=\"cmd-opt-diff" dongsheng@627: "\">-r</option> and <option role=\"cmd-opt-diff\">-N</option> options to " dongsheng@627: "<command>diff</command> to recursively generate a patch between the " dongsheng@627: "unmodified directory and the modified one. The result would be that the name " dongsheng@627: "of the unmodified directory would be at the front of the left-hand path in " dongsheng@627: "every file header, and the name of the modified directory would be at the " dongsheng@627: "front of the right-hand path." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:535 dongsheng@627: msgid "" dongsheng@627: "Since someone receiving a patch from the Alices of the net would be unlikely " dongsheng@627: "to have unmodified and modified directories with exactly the same names, the " dongsheng@627: "<command>patch</command> command has a <option role=\"cmd-opt-patch\">-p</" dongsheng@627: "option> option that indicates the number of leading path name components to " dongsheng@627: "strip when trying to apply a patch. This number is called the " dongsheng@627: "<emphasis>strip count</emphasis>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:543 dongsheng@627: msgid "" dongsheng@627: "An option of <quote><literal>-p1</literal></quote> means <quote>use a strip " dongsheng@627: "count of one</quote>. If <command>patch</command> sees a file name " dongsheng@627: "<filename>foo/bar/baz</filename> in a file header, it will strip " dongsheng@627: "<filename>foo</filename> and try to patch a file named <filename>bar/baz</" dongsheng@627: "filename>. (Strictly speaking, the strip count refers to the number of " dongsheng@627: "<emphasis>path separators</emphasis> (and the components that go with them ) " dongsheng@627: "to strip. A strip count of one will turn <filename>foo/bar</filename> into " dongsheng@627: "<filename>bar</filename>, but <filename>/foo/bar</filename> (notice the extra " dongsheng@627: "leading slash) into <filename>foo/bar</filename>.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:556 dongsheng@627: msgid "" dongsheng@627: "The <quote>standard</quote> strip count for patches is one; almost all " dongsheng@627: "patches contain one leading path name component that needs to be stripped. " dongsheng@627: "Mercurial's <command role=\"hg-cmd\">hg diff</command> command generates path " dongsheng@627: "names in this form, and the <command role=\"hg-cmd\">hg import</command> " dongsheng@627: "command and MQ expect patches to have a strip count of one." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:564 dongsheng@627: msgid "" dongsheng@627: "If you receive a patch from someone that you want to add to your patch queue, " dongsheng@627: "and the patch needs a strip count other than one, you cannot just <command " dongsheng@627: "role=\"hg-ext-mq\">qimport</command> the patch, because <command role=\"hg-" dongsheng@627: "ext-mq\">qimport</command> does not yet have a <literal>-p</literal> option " dongsheng@627: "(see <ulink role=\"hg-bug\" url=\"http://www.selenic.com/mercurial/bts/" dongsheng@627: "issue311\">issue 311</ulink>). Your best bet is to <command role=\"hg-ext-mq" dongsheng@627: "\">qnew</command> a patch of your own, then use <command>patch -pN</command> " dongsheng@627: "to apply their patch, followed by <command role=\"hg-cmd\">hg addremove</" dongsheng@627: "command> to pick up any files added or removed by the patch, followed by " dongsheng@627: "<command role=\"hg-ext-mq\">hg qrefresh</command>. This complexity may become " dongsheng@627: "unnecessary; see <ulink role=\"hg-bug\" url=\"http://www.selenic.com/" dongsheng@627: "mercurial/bts/issue311\">issue 311</ulink> for details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:583 dongsheng@627: msgid "Strategies for applying a patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:585 dongsheng@627: msgid "" dongsheng@627: "When <command>patch</command> applies a hunk, it tries a handful of " dongsheng@627: "successively less accurate strategies to try to make the hunk apply. This " dongsheng@627: "falling-back technique often makes it possible to take a patch that was " dongsheng@627: "generated against an old version of a file, and apply it against a newer " dongsheng@627: "version of that file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:592 dongsheng@627: msgid "" dongsheng@627: "First, <command>patch</command> tries an exact match, where the line numbers, " dongsheng@627: "the context, and the text to be modified must apply exactly. If it cannot " dongsheng@627: "make an exact match, it tries to find an exact match for the context, without " dongsheng@627: "honouring the line numbering information. If this succeeds, it prints a line " dongsheng@627: "of output saying that the hunk was applied, but at some <emphasis>offset</" dongsheng@627: "emphasis> from the original line number." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:601 dongsheng@627: msgid "" dongsheng@627: "If a context-only match fails, <command>patch</command> removes the first and " dongsheng@627: "last lines of the context, and tries a <emphasis>reduced</emphasis> context-" dongsheng@627: "only match. If the hunk with reduced context succeeds, it prints a message " dongsheng@627: "saying that it applied the hunk with a <emphasis>fuzz factor</emphasis> (the " dongsheng@627: "number after the fuzz factor indicates how many lines of context " dongsheng@627: "<command>patch</command> had to trim before the patch applied)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:610 dongsheng@627: msgid "" dongsheng@627: "When neither of these techniques works, <command>patch</command> prints a " dongsheng@627: "message saying that the hunk in question was rejected. It saves rejected " dongsheng@627: "hunks (also simply called <quote>rejects</quote>) to a file with the same " dongsheng@627: "name, and an added <filename role=\"special\">.rej</filename> extension. It " dongsheng@627: "also saves an unmodified copy of the file with a <filename role=\"special\">." dongsheng@627: "orig</filename> extension; the copy of the file without any extensions will " dongsheng@627: "contain any changes made by hunks that <emphasis>did</emphasis> apply " dongsheng@627: "cleanly. If you have a patch that modifies <filename>foo</filename> with six " dongsheng@627: "hunks, and one of them fails to apply, you will have: an unmodified " dongsheng@627: "<filename>foo.orig</filename>, a <filename>foo.rej</filename> containing one " dongsheng@627: "hunk, and <filename>foo</filename>, containing the changes made by the five " dongsheng@627: "successful hunks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:628 dongsheng@627: msgid "Some quirks of patch representation" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:630 dongsheng@627: msgid "" dongsheng@627: "There are a few useful things to know about how <command>patch</command> " dongsheng@627: "works with files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:633 dongsheng@627: msgid "" dongsheng@627: "This should already be obvious, but <command>patch</command> cannot handle " dongsheng@627: "binary files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:637 dongsheng@627: msgid "" dongsheng@627: "Neither does it care about the executable bit; it creates new files as " dongsheng@627: "readable, but not executable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:641 dongsheng@627: msgid "" dongsheng@627: "<command>patch</command> treats the removal of a file as a diff between the " dongsheng@627: "file to be removed and the empty file. So your idea of <quote>I deleted this " dongsheng@627: "file</quote> looks like <quote>every line of this file was deleted</quote> in " dongsheng@627: "a patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:647 dongsheng@627: msgid "" dongsheng@627: "It treats the addition of a file as a diff between the empty file and the " dongsheng@627: "file to be added. So in a patch, your idea of <quote>I added this file</" dongsheng@627: "quote> looks like <quote>every line of this file was added</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:653 dongsheng@627: msgid "" dongsheng@627: "It treats a renamed file as the removal of the old name, and the addition of " dongsheng@627: "the new name. This means that renamed files have a big footprint in " dongsheng@627: "patches. (Note also that Mercurial does not currently try to infer when " dongsheng@627: "files have been renamed or copied in a patch.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:659 dongsheng@627: msgid "" dongsheng@627: "<command>patch</command> cannot represent empty files, so you cannot use a " dongsheng@627: "patch to represent the notion <quote>I added this empty file to the tree</" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:666 dongsheng@627: msgid "Beware the fuzz" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:668 dongsheng@627: msgid "" dongsheng@627: "While applying a hunk at an offset, or with a fuzz factor, will often be " dongsheng@627: "completely successful, these inexact techniques naturally leave open the " dongsheng@627: "possibility of corrupting the patched file. The most common cases typically " dongsheng@627: "involve applying a patch twice, or at an incorrect location in the file. If " dongsheng@627: "<command>patch</command> or <command role=\"hg-ext-mq\">qpush</command> ever " dongsheng@627: "mentions an offset or fuzz factor, you should make sure that the modified " dongsheng@627: "files are correct afterwards." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:678 dongsheng@627: msgid "" dongsheng@627: "It's often a good idea to refresh a patch that has applied with an offset or " dongsheng@627: "fuzz factor; refreshing the patch generates new context information that will " dongsheng@627: "make it apply cleanly. I say <quote>often,</quote> not <quote>always,</" dongsheng@627: "quote> because sometimes refreshing a patch will make it fail to apply " dongsheng@627: "against a different revision of the underlying files. In some cases, such as " dongsheng@627: "when you're maintaining a patch that must sit on top of multiple versions of " dongsheng@627: "a source tree, it's acceptable to have a patch apply with some fuzz, provided " dongsheng@627: "you've verified the results of the patching process in such cases." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:691 dongsheng@627: msgid "Handling rejection" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:693 dongsheng@627: msgid "" dongsheng@627: "If <command role=\"hg-ext-mq\">qpush</command> fails to apply a patch, it " dongsheng@627: "will print an error message and exit. If it has left <filename role=\"special" dongsheng@627: "\">.rej</filename> files behind, it is usually best to fix up the rejected " dongsheng@627: "hunks before you push more patches or do any further work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:699 dongsheng@627: msgid "" dongsheng@627: "If your patch <emphasis>used to</emphasis> apply cleanly, and no longer does " dongsheng@627: "because you've changed the underlying code that your patches are based on, " dongsheng@627: "Mercurial Queues can help; see section <xref linkend=\"sec.mq.merge\"/> for " dongsheng@627: "details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:705 dongsheng@627: msgid "" dongsheng@627: "Unfortunately, there aren't any great techniques for dealing with rejected " dongsheng@627: "hunks. Most often, you'll need to view the <filename role=\"special\">.rej</" dongsheng@627: "filename> file and edit the target file, applying the rejected hunks by hand." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:710 dongsheng@627: msgid "" dongsheng@627: "If you're feeling adventurous, Neil Brown, a Linux kernel hacker, wrote a " dongsheng@627: "tool called <command>wiggle</command> <citation>web:wiggle</citation>, which " dongsheng@627: "is more vigorous than <command>patch</command> in its attempts to make a " dongsheng@627: "patch apply." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:716 dongsheng@627: msgid "" dongsheng@627: "Another Linux kernel hacker, Chris Mason (the author of Mercurial Queues), " dongsheng@627: "wrote a similar tool called <command>mpatch</command> <citation>web:mpatch</" dongsheng@627: "citation>, which takes a simple approach to automating the application of " dongsheng@627: "hunks rejected by <command>patch</command>. The <command>mpatch</command> " dongsheng@627: "command can help with four common reasons that a hunk may be rejected:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:725 dongsheng@627: msgid "The context in the middle of a hunk has changed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:728 dongsheng@627: msgid "A hunk is missing some context at the beginning or end." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:731 dongsheng@627: msgid "" dongsheng@627: "A large hunk might apply better&emdash;either entirely or in part&emdash;if " dongsheng@627: "it was broken up into smaller hunks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:735 dongsheng@627: msgid "" dongsheng@627: "A hunk removes lines with slightly different content than those currently " dongsheng@627: "present in the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:739 dongsheng@627: msgid "" dongsheng@627: "If you use <command>wiggle</command> or <command>mpatch</command>, you should " dongsheng@627: "be doubly careful to check your results when you're done. In fact, " dongsheng@627: "<command>mpatch</command> enforces this method of double-checking the tool's " dongsheng@627: "output, by automatically dropping you into a merge program when it has done " dongsheng@627: "its job, so that you can verify its work and finish off any remaining merges." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:751 dongsheng@627: msgid "Getting the best performance out of MQ" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:753 dongsheng@627: msgid "" dongsheng@627: "MQ is very efficient at handling a large number of patches. I ran some " dongsheng@627: "performance experiments in mid-2006 for a talk that I gave at the 2006 " dongsheng@627: "EuroPython conference <citation>web:europython</citation>. I used as my data " dongsheng@627: "set the Linux 2.6.17-mm1 patch series, which consists of 1,738 patches. I " dongsheng@627: "applied these on top of a Linux kernel repository containing all 27,472 " dongsheng@627: "revisions between Linux 2.6.12-rc2 and Linux 2.6.17." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:762 dongsheng@627: msgid "" dongsheng@627: "On my old, slow laptop, I was able to <command role=\"hg-cmd\">hg qpush " dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</option></command> all 1,738 " dongsheng@627: "patches in 3.5 minutes, and <command role=\"hg-cmd\">hg qpop <option role=" dongsheng@627: "\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> them all in 30 seconds. " dongsheng@627: "(On a newer laptop, the time to push all patches dropped to two minutes.) I " dongsheng@627: "could <command role=\"hg-ext-mq\">qrefresh</command> one of the biggest " dongsheng@627: "patches (which made 22,779 lines of changes to 287 files) in 6.6 seconds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:773 dongsheng@627: msgid "" dongsheng@627: "Clearly, MQ is well suited to working in large trees, but there are a few " dongsheng@627: "tricks you can use to get the best performance of it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:777 dongsheng@627: msgid "" dongsheng@627: "First of all, try to <quote>batch</quote> operations together. Every time " dongsheng@627: "you run <command role=\"hg-ext-mq\">qpush</command> or <command role=\"hg-ext-" dongsheng@627: "mq\">qpop</command>, these commands scan the working directory once to make " dongsheng@627: "sure you haven't made some changes and then forgotten to run <command role=" dongsheng@627: "\"hg-ext-mq\">qrefresh</command>. On a small tree, the time that this scan " dongsheng@627: "takes is unnoticeable. However, on a medium-sized tree (containing tens of " dongsheng@627: "thousands of files), it can take a second or more." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:788 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpush</command> and <command role=\"hg-ext-mq" dongsheng@627: "\">qpop</command> commands allow you to push and pop multiple patches at a " dongsheng@627: "time. You can identify the <quote>destination patch</quote> that you want to " dongsheng@627: "end up at. When you <command role=\"hg-ext-mq\">qpush</command> with a " dongsheng@627: "destination specified, it will push patches until that patch is at the top of " dongsheng@627: "the applied stack. When you <command role=\"hg-ext-mq\">qpop</command> to a " dongsheng@627: "destination, MQ will pop patches until the destination patch is at the top." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:798 dongsheng@627: msgid "" dongsheng@627: "You can identify a destination patch using either the name of the patch, or " dongsheng@627: "by number. If you use numeric addressing, patches are counted from zero; " dongsheng@627: "this means that the first patch is zero, the second is one, and so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:805 dongsheng@627: msgid "Updating your patches when the underlying code changes" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:808 dongsheng@627: msgid "" dongsheng@627: "It's common to have a stack of patches on top of an underlying repository " dongsheng@627: "that you don't modify directly. If you're working on changes to third-party " dongsheng@627: "code, or on a feature that is taking longer to develop than the rate of " dongsheng@627: "change of the code beneath, you will often need to sync up with the " dongsheng@627: "underlying code, and fix up any hunks in your patches that no longer apply. " dongsheng@627: "This is called <emphasis>rebasing</emphasis> your patch series." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:817 dongsheng@627: msgid "" dongsheng@627: "The simplest way to do this is to <command role=\"hg-cmd\">hg qpop <option " dongsheng@627: "role=\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> your patches, then " dongsheng@627: "<command role=\"hg-cmd\">hg pull</command> changes into the underlying " dongsheng@627: "repository, and finally <command role=\"hg-cmd\">hg qpush <option role=\"hg-" dongsheng@627: "ext-mq-cmd-qpop-opt\">hg -a</option></command> your patches again. MQ will " dongsheng@627: "stop pushing any time it runs across a patch that fails to apply during " dongsheng@627: "conflicts, allowing you to fix your conflicts, <command role=\"hg-ext-mq" dongsheng@627: "\">qrefresh</command> the affected patch, and continue pushing until you have " dongsheng@627: "fixed your entire stack." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:829 dongsheng@627: msgid "" dongsheng@627: "This approach is easy to use and works well if you don't expect changes to " dongsheng@627: "the underlying code to affect how well your patches apply. If your patch " dongsheng@627: "stack touches code that is modified frequently or invasively in the " dongsheng@627: "underlying repository, however, fixing up rejected hunks by hand quickly " dongsheng@627: "becomes tiresome." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:836 dongsheng@627: msgid "" dongsheng@627: "It's possible to partially automate the rebasing process. If your patches " dongsheng@627: "apply cleanly against some revision of the underlying repo, MQ can use this " dongsheng@627: "information to help you to resolve conflicts between your patches and a " dongsheng@627: "different revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:842 dongsheng@627: msgid "The process is a little involved." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:844 dongsheng@627: msgid "" dongsheng@627: "To begin, <command role=\"hg-cmd\">hg qpush -a</command> all of your patches " dongsheng@627: "on top of the revision where you know that they apply cleanly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:848 dongsheng@627: msgid "" dongsheng@627: "Save a backup copy of your patch directory using <command role=\"hg-cmd\">hg " dongsheng@627: "qsave <option role=\"hg-ext-mq-cmd-qsave-opt\">hg -e</option> <option role=" dongsheng@627: "\"hg-ext-mq-cmd-qsave-opt\">hg -c</option></command>. This prints the name " dongsheng@627: "of the directory that it has saved the patches in. It will save the patches " dongsheng@627: "to a directory called <filename role=\"special\" class=\"directory\">.hg/" dongsheng@627: "patches.N</filename>, where <literal>N</literal> is a small integer. It also " dongsheng@627: "commits a <quote>save changeset</quote> on top of your applied patches; this " dongsheng@627: "is for internal book-keeping, and records the states of the <filename role=" dongsheng@627: "\"special\">series</filename> and <filename role=\"special\">status</" dongsheng@627: "filename> files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:862 dongsheng@627: msgid "" dongsheng@627: "Use <command role=\"hg-cmd\">hg pull</command> to bring new changes into the " dongsheng@627: "underlying repository. (Don't run <command role=\"hg-cmd\">hg pull -u</" dongsheng@627: "command>; see below for why.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:867 dongsheng@627: msgid "" dongsheng@627: "Update to the new tip revision, using <command role=\"hg-cmd\">hg update " dongsheng@627: "<option role=\"hg-opt-update\">-C</option></command> to override the patches " dongsheng@627: "you have pushed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:872 dongsheng@627: msgid "" dongsheng@627: "Merge all patches using \\hgcmdargs{qpush}{<option role=\"hg-ext-mq-cmd-qpush-" dongsheng@627: "opt\">hg -m</option> <option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</" dongsheng@627: "option>}. The <option role=\"hg-ext-mq-cmd-qpush-opt\">hg -m</option> option " dongsheng@627: "to <command role=\"hg-ext-mq\">qpush</command> tells MQ to perform a three-" dongsheng@627: "way merge if the patch fails to apply." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:882 dongsheng@627: msgid "" dongsheng@627: "During the <command role=\"hg-cmd\">hg qpush <option role=\"hg-ext-mq-cmd-" dongsheng@627: "qpush-opt\">hg -m</option></command>, each patch in the <filename role=" dongsheng@627: "\"special\">series</filename> file is applied normally. If a patch applies " dongsheng@627: "with fuzz or rejects, MQ looks at the queue you <command role=\"hg-ext-mq" dongsheng@627: "\">qsave</command>d, and performs a three-way merge with the corresponding " dongsheng@627: "changeset. This merge uses Mercurial's normal merge machinery, so it may pop " dongsheng@627: "up a GUI merge tool to help you to resolve problems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:892 dongsheng@627: msgid "" dongsheng@627: "When you finish resolving the effects of a patch, MQ refreshes your patch " dongsheng@627: "based on the result of the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:895 dongsheng@627: msgid "" dongsheng@627: "At the end of this process, your repository will have one extra head from the " dongsheng@627: "old patch queue, and a copy of the old patch queue will be in <filename role=" dongsheng@627: "\"special\" class=\"directory\">.hg/patches.N</filename>. You can remove the " dongsheng@627: "extra head using <command role=\"hg-cmd\">hg qpop -a -n patches.N</command> " dongsheng@627: "or <command role=\"hg-cmd\">hg strip</command>. You can delete <filename " dongsheng@627: "role=\"special\" class=\"directory\">.hg/patches.N</filename> once you are " dongsheng@627: "sure that you no longer need it as a backup." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:907 dongsheng@627: msgid "Identifying patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:909 dongsheng@627: msgid "" dongsheng@627: "MQ commands that work with patches let you refer to a patch either by using " dongsheng@627: "its name or by a number. By name is obvious enough; pass the name " dongsheng@627: "<filename>foo.patch</filename> to <command role=\"hg-ext-mq\">qpush</" dongsheng@627: "command>, for example, and it will push patches until <filename>foo.patch</" dongsheng@627: "filename> is applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:916 dongsheng@627: msgid "" dongsheng@627: "As a shortcut, you can refer to a patch using both a name and a numeric " dongsheng@627: "offset; <literal>foo.patch-2</literal> means <quote>two patches before " dongsheng@627: "<literal>foo.patch</literal></quote>, while <literal>bar.patch+4</literal> " dongsheng@627: "means <quote>four patches after <literal>bar.patch</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:922 dongsheng@627: msgid "" dongsheng@627: "Referring to a patch by index isn't much different. The first patch printed " dongsheng@627: "in the output of <command role=\"hg-ext-mq\">qseries</command> is patch zero " dongsheng@627: "(yes, it's one of those start-at-zero counting systems); the second is patch " dongsheng@627: "one; and so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:928 dongsheng@627: msgid "" dongsheng@627: "MQ also makes it easy to work with patches when you are using normal " dongsheng@627: "Mercurial commands. Every command that accepts a changeset ID will also " dongsheng@627: "accept the name of an applied patch. MQ augments the tags normally in the " dongsheng@627: "repository with an eponymous one for each applied patch. In addition, the " dongsheng@627: "special tags \\index{tags!special tag names!<literal>qbase</literal>}" dongsheng@627: "<literal>qbase</literal> and \\index{tags!special tag names!<literal>qtip</" dongsheng@627: "literal>}<literal>qtip</literal> identify the <quote>bottom-most</quote> and " dongsheng@627: "topmost applied patches, respectively." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:940 dongsheng@627: msgid "" dongsheng@627: "These additions to Mercurial's normal tagging capabilities make dealing with " dongsheng@627: "patches even more of a breeze." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:943 dongsheng@627: msgid "Want to patchbomb a mailing list with your latest series of changes?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:947 dongsheng@627: msgid "" dongsheng@627: "(Don't know what <quote>patchbombing</quote> is? See section <xref linkend=" dongsheng@627: "\"sec.hgext.patchbomb\"/>.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:950 dongsheng@627: msgid "" dongsheng@627: "Need to see all of the patches since <literal>foo.patch</literal> that have " dongsheng@627: "touched files in a subdirectory of your tree?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><programlisting><emphasis> dongsheng@627: #: ../en/ch12-mq.xml:954 dongsheng@627: msgid "subdir" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:959 dongsheng@627: msgid "" dongsheng@627: "Because MQ makes the names of patches available to the rest of Mercurial " dongsheng@627: "through its normal internal tag machinery, you don't need to type in the " dongsheng@627: "entire name of a patch when you want to identify it by name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:964 dongsheng@627: msgid "" dongsheng@627: "Another nice consequence of representing patch names as tags is that when you " dongsheng@627: "run the <command role=\"hg-cmd\">hg log</command> command, it will display a " dongsheng@627: "patch's name as a tag, simply as part of its normal output. This makes it " dongsheng@627: "easy to visually distinguish applied patches from underlying <quote>normal</" dongsheng@627: "quote> revisions. The following example shows a few normal Mercurial " dongsheng@627: "commands in use with applied patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:977 dongsheng@627: msgid "Useful things to know about" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:979 dongsheng@627: msgid "" dongsheng@627: "There are a number of aspects of MQ usage that don't fit tidily into sections " dongsheng@627: "of their own, but that are good to know. Here they are, in one place." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:984 dongsheng@627: msgid "" dongsheng@627: "Normally, when you <command role=\"hg-ext-mq\">qpop</command> a patch and " dongsheng@627: "<command role=\"hg-ext-mq\">qpush</command> it again, the changeset that " dongsheng@627: "represents the patch after the pop/push will have a <emphasis>different " dongsheng@627: "identity</emphasis> than the changeset that represented the hash beforehand. " dongsheng@627: "See section <xref linkend=\"sec.mqref.cmd.qpush\"/> for information as to why " dongsheng@627: "this is." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:993 dongsheng@627: msgid "" dongsheng@627: "It's not a good idea to <command role=\"hg-cmd\">hg merge</command> changes " dongsheng@627: "from another branch with a patch changeset, at least if you want to maintain " dongsheng@627: "the <quote>patchiness</quote> of that changeset and changesets below it on " dongsheng@627: "the patch stack. If you try to do this, it will appear to succeed, but MQ " dongsheng@627: "will become confused." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1004 dongsheng@627: msgid "Managing patches in a repository" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1006 dongsheng@627: msgid "" dongsheng@627: "Because MQ's <filename role=\"special\" class=\"directory\">.hg/patches</" dongsheng@627: "filename> directory resides outside a Mercurial repository's working " dongsheng@627: "directory, the <quote>underlying</quote> Mercurial repository knows nothing " dongsheng@627: "about the management or presence of patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1012 dongsheng@627: msgid "" dongsheng@627: "This presents the interesting possibility of managing the contents of the " dongsheng@627: "patch directory as a Mercurial repository in its own right. This can be a " dongsheng@627: "useful way to work. For example, you can work on a patch for a while, " dongsheng@627: "<command role=\"hg-ext-mq\">qrefresh</command> it, then <command role=\"hg-cmd" dongsheng@627: "\">hg commit</command> the current state of the patch. This lets you " dongsheng@627: "<quote>roll back</quote> to that version of the patch later on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1021 dongsheng@627: msgid "" dongsheng@627: "You can then share different versions of the same patch stack among multiple " dongsheng@627: "underlying repositories. I use this when I am developing a Linux kernel " dongsheng@627: "feature. I have a pristine copy of my kernel sources for each of several CPU " dongsheng@627: "architectures, and a cloned repository under each that contains the patches I " dongsheng@627: "am working on. When I want to test a change on a different architecture, I " dongsheng@627: "push my current patches to the patch repository associated with that kernel " dongsheng@627: "tree, pop and push all of my patches, and build and test that kernel." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1031 dongsheng@627: msgid "" dongsheng@627: "Managing patches in a repository makes it possible for multiple developers to " dongsheng@627: "work on the same patch series without colliding with each other, all on top " dongsheng@627: "of an underlying source base that they may or may not control." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1037 dongsheng@627: msgid "MQ support for patch repositories" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1039 dongsheng@627: msgid "" dongsheng@627: "MQ helps you to work with the <filename role=\"special\" class=\"directory\">." dongsheng@627: "hg/patches</filename> directory as a repository; when you prepare a " dongsheng@627: "repository for working with patches using <command role=\"hg-ext-mq\">qinit</" dongsheng@627: "command>, you can pass the <option role=\"hg-ext-mq-cmd-qinit-opt\">hg -c</" dongsheng@627: "option> option to create the <filename role=\"special\" class=\"directory\">." dongsheng@627: "hg/patches</filename> directory as a Mercurial repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch12-mq.xml:1049 dongsheng@627: msgid "" dongsheng@627: "If you forget to use the <option role=\"hg-ext-mq-cmd-qinit-opt\">hg -c</" dongsheng@627: "option> option, you can simply go into the <filename role=\"special\" class=" dongsheng@627: "\"directory\">.hg/patches</filename> directory at any time and run <command " dongsheng@627: "role=\"hg-cmd\">hg init</command>. Don't forget to add an entry for the " dongsheng@627: "<filename role=\"special\">status</filename> file to the <filename role=" dongsheng@627: "\"special\">.hgignore</filename> file, though" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch12-mq.xml:1058 dongsheng@627: msgid "" dongsheng@627: "(<command role=\"hg-cmd\">hg qinit <option role=\"hg-ext-mq-cmd-qinit-opt" dongsheng@627: "\">hg -c</option></command> does this for you automatically); you " dongsheng@627: "<emphasis>really</emphasis> don't want to manage the <filename role=\"special" dongsheng@627: "\">status</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1065 dongsheng@627: msgid "" dongsheng@627: "As a convenience, if MQ notices that the <filename class=\"directory\">.hg/" dongsheng@627: "patches</filename> directory is a repository, it will automatically <command " dongsheng@627: "role=\"hg-cmd\">hg add</command> every patch that you create and import." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1070 dongsheng@627: msgid "" dongsheng@627: "MQ provides a shortcut command, <command role=\"hg-ext-mq\">qcommit</" dongsheng@627: "command>, that runs <command role=\"hg-cmd\">hg commit</command> in the " dongsheng@627: "<filename role=\"special\" class=\"directory\">.hg/patches</filename> " dongsheng@627: "directory. This saves some bothersome typing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1076 dongsheng@627: msgid "" dongsheng@627: "Finally, as a convenience to manage the patch directory, you can define the " dongsheng@627: "alias <command>mq</command> on Unix systems. For example, on Linux systems " dongsheng@627: "using the <command>bash</command> shell, you can include the following " dongsheng@627: "snippet in your <filename role=\"home\">~/.bashrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1086 dongsheng@627: msgid "" dongsheng@627: "You can then issue commands of the form <command>mq pull</command> from the " dongsheng@627: "main repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1091 dongsheng@627: msgid "A few things to watch out for" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1093 dongsheng@627: msgid "" dongsheng@627: "MQ's support for working with a repository full of patches is limited in a " dongsheng@627: "few small respects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1096 dongsheng@627: msgid "" dongsheng@627: "MQ cannot automatically detect changes that you make to the patch directory. " dongsheng@627: "If you <command role=\"hg-cmd\">hg pull</command>, manually edit, or <command " dongsheng@627: "role=\"hg-cmd\">hg update</command> changes to patches or the <filename role=" dongsheng@627: "\"special\">series</filename> file, you will have to <command role=\"hg-cmd" dongsheng@627: "\">hg qpop <option role=\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> " dongsheng@627: "and then <command role=\"hg-cmd\">hg qpush <option role=\"hg-ext-mq-cmd-qpush-" dongsheng@627: "opt\">hg -a</option></command> in the underlying repository to see those " dongsheng@627: "changes show up there. If you forget to do this, you can confuse MQ's idea " dongsheng@627: "of which patches are applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1112 dongsheng@627: msgid "Third party tools for working with patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1114 dongsheng@627: msgid "" dongsheng@627: "Once you've been working with patches for a while, you'll find yourself " dongsheng@627: "hungry for tools that will help you to understand and manipulate the patches " dongsheng@627: "you're dealing with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1118 dongsheng@627: msgid "" dongsheng@627: "The <command>diffstat</command> command <citation>web:diffstat</citation> " dongsheng@627: "generates a histogram of the modifications made to each file in a patch. It " dongsheng@627: "provides a good way to <quote>get a sense of</quote> a patch&emdash;which " dongsheng@627: "files it affects, and how much change it introduces to each file and as a " dongsheng@627: "whole. (I find that it's a good idea to use <command>diffstat</command>'s " dongsheng@627: "<option role=\"cmd-opt-diffstat\">-p</option> option as a matter of course, " dongsheng@627: "as otherwise it will try to do clever things with prefixes of file names that " dongsheng@627: "inevitably confuse at least me.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1132 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"package\">patchutils</literal> package <citation>web:" dongsheng@627: "patchutils</citation> is invaluable. It provides a set of small utilities " dongsheng@627: "that follow the <quote>Unix philosophy;</quote> each does one useful thing " dongsheng@627: "with a patch. The <literal role=\"package\">patchutils</literal> command I " dongsheng@627: "use most is <command>filterdiff</command>, which extracts subsets from a " dongsheng@627: "patch file. For example, given a patch that modifies hundreds of files " dongsheng@627: "across dozens of directories, a single invocation of <command>filterdiff</" dongsheng@627: "command> can generate a smaller patch that only touches files whose names " dongsheng@627: "match a particular glob pattern. See section <xref linkend=\"mq-collab.tips." dongsheng@627: "interdiff\"/> for another example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1148 dongsheng@627: msgid "Good ways to work with patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1150 dongsheng@627: msgid "" dongsheng@627: "Whether you are working on a patch series to submit to a free software or " dongsheng@627: "open source project, or a series that you intend to treat as a sequence of " dongsheng@627: "regular changesets when you're done, you can use some simple techniques to " dongsheng@627: "keep your work well organised." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1156 dongsheng@627: msgid "" dongsheng@627: "Give your patches descriptive names. A good name for a patch might be " dongsheng@627: "<filename>rework-device-alloc.patch</filename>, because it will immediately " dongsheng@627: "give you a hint what the purpose of the patch is. Long names shouldn't be a " dongsheng@627: "problem; you won't be typing the names often, but you <emphasis>will</" dongsheng@627: "emphasis> be running commands like <command role=\"hg-ext-mq\">qapplied</" dongsheng@627: "command> and <command role=\"hg-ext-mq\">qtop</command> over and over. Good " dongsheng@627: "naming becomes especially important when you have a number of patches to work " dongsheng@627: "with, or if you are juggling a number of different tasks and your patches " dongsheng@627: "only get a fraction of your attention." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1168 dongsheng@627: msgid "" dongsheng@627: "Be aware of what patch you're working on. Use the <command role=\"hg-ext-mq" dongsheng@627: "\">qtop</command> command and skim over the text of your patches " dongsheng@627: "frequently&emdash;for example, using <command role=\"hg-cmd\">hg tip <option " dongsheng@627: "role=\"hg-opt-tip\">-p</option></command>)&emdash;to be sure of where you " dongsheng@627: "stand. I have several times worked on and <command role=\"hg-ext-mq" dongsheng@627: "\">qrefresh</command>ed a patch other than the one I intended, and it's often " dongsheng@627: "tricky to migrate changes into the right patch after making them in the wrong " dongsheng@627: "one." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1178 dongsheng@627: msgid "" dongsheng@627: "For this reason, it is very much worth investing a little time to learn how " dongsheng@627: "to use some of the third-party tools I described in section <xref linkend=" dongsheng@627: "\"sec.mq.tools\"/>, particularly <command>diffstat</command> and " dongsheng@627: "<command>filterdiff</command>. The former will give you a quick idea of what " dongsheng@627: "changes your patch is making, while the latter makes it easy to splice hunks " dongsheng@627: "selectively out of one patch and into another." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1189 dongsheng@627: msgid "MQ cookbook" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1192 dongsheng@627: msgid "Manage <quote>trivial</quote> patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1194 dongsheng@627: msgid "" dongsheng@627: "Because the overhead of dropping files into a new Mercurial repository is so " dongsheng@627: "low, it makes a lot of sense to manage patches this way even if you simply " dongsheng@627: "want to make a few changes to a source tarball that you downloaded." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1199 dongsheng@627: msgid "" dongsheng@627: "Begin by downloading and unpacking the source tarball, and turning it into a " dongsheng@627: "Mercurial repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1204 dongsheng@627: msgid "Continue by creating a patch stack and making your changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1209 dongsheng@627: msgid "" dongsheng@627: "Let's say a few weeks or months pass, and your package author releases a new " dongsheng@627: "version. First, bring their changes into the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1215 dongsheng@627: msgid "" dongsheng@627: "The pipeline starting with <command role=\"hg-cmd\">hg locate</command> above " dongsheng@627: "deletes all files in the working directory, so that <command role=\"hg-cmd" dongsheng@627: "\">hg commit</command>'s <option role=\"hg-opt-commit\">--addremove</option> " dongsheng@627: "option can actually tell which files have really been removed in the newer " dongsheng@627: "version of the source." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1223 dongsheng@627: msgid "Finally, you can apply your patches on top of the new tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1230 dongsheng@627: msgid "Combining entire patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1232 dongsheng@627: msgid "" dongsheng@627: "MQ provides a command, <command role=\"hg-ext-mq\">qfold</command> that lets " dongsheng@627: "you combine entire patches. This <quote>folds</quote> the patches you name, " dongsheng@627: "in the order you name them, into the topmost applied patch, and concatenates " dongsheng@627: "their descriptions onto the end of its description. The patches that you " dongsheng@627: "fold must be unapplied before you fold them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1240 dongsheng@627: msgid "" dongsheng@627: "The order in which you fold patches matters. If your topmost applied patch " dongsheng@627: "is <literal>foo</literal>, and you <command role=\"hg-ext-mq\">qfold</" dongsheng@627: "command> <literal>bar</literal> and <literal>quux</literal> into it, you will " dongsheng@627: "end up with a patch that has the same effect as if you applied first " dongsheng@627: "<literal>foo</literal>, then <literal>bar</literal>, followed by " dongsheng@627: "<literal>quux</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1251 dongsheng@627: msgid "Merging part of one patch into another" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1253 dongsheng@627: msgid "" dongsheng@627: "Merging <emphasis>part</emphasis> of one patch into another is more difficult " dongsheng@627: "than combining entire patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1257 dongsheng@627: msgid "" dongsheng@627: "If you want to move changes to entire files, you can use <command>filterdiff</" dongsheng@627: "command>'s <option role=\"cmd-opt-filterdiff\">-i</option> and <option role=" dongsheng@627: "\"cmd-opt-filterdiff\">-x</option> options to choose the modifications to " dongsheng@627: "snip out of one patch, concatenating its output onto the end of the patch you " dongsheng@627: "want to merge into. You usually won't need to modify the patch you've merged " dongsheng@627: "the changes from. Instead, MQ will report some rejected hunks when you " dongsheng@627: "<command role=\"hg-ext-mq\">qpush</command> it (from the hunks you moved into " dongsheng@627: "the other patch), and you can simply <command role=\"hg-ext-mq\">qrefresh</" dongsheng@627: "command> the patch to drop the duplicate hunks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1270 dongsheng@627: msgid "" dongsheng@627: "If you have a patch that has multiple hunks modifying a file, and you only " dongsheng@627: "want to move a few of those hunks, the job becomes more messy, but you can " dongsheng@627: "still partly automate it. Use <command>lsdiff -nvv</command> to print some " dongsheng@627: "metadata about the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1278 dongsheng@627: msgid "This command prints three different kinds of number:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:1281 dongsheng@627: msgid "" dongsheng@627: "(in the first column) a <emphasis>file number</emphasis> to identify each " dongsheng@627: "file modified in the patch;" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:1285 dongsheng@627: msgid "" dongsheng@627: "(on the next line, indented) the line number within a modified file where a " dongsheng@627: "hunk starts; and" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:1288 dongsheng@627: msgid "" dongsheng@627: "(on the same line) a <emphasis>hunk number</emphasis> to identify that hunk." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1292 dongsheng@627: msgid "" dongsheng@627: "You'll have to use some visual inspection, and reading of the patch, to " dongsheng@627: "identify the file and hunk numbers you'll want, but you can then pass them to " dongsheng@627: "to <command>filterdiff</command>'s <option role=\"cmd-opt-filterdiff\">--" dongsheng@627: "files</option> and <option role=\"cmd-opt-filterdiff\">--hunks</option> " dongsheng@627: "options, to select exactly the file and hunk you want to extract." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1300 dongsheng@627: msgid "" dongsheng@627: "Once you have this hunk, you can concatenate it onto the end of your " dongsheng@627: "destination patch and continue with the remainder of section <xref linkend=" dongsheng@627: "\"sec.mq.combine\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1307 dongsheng@627: msgid "Differences between quilt and MQ" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1309 dongsheng@627: msgid "" dongsheng@627: "If you are already familiar with quilt, MQ provides a similar command set. " dongsheng@627: "There are a few differences in the way that it works." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1313 dongsheng@627: msgid "" dongsheng@627: "You will already have noticed that most quilt commands have MQ counterparts " dongsheng@627: "that simply begin with a <quote><literal>q</literal></quote>. The exceptions " dongsheng@627: "are quilt's <literal>add</literal> and <literal>remove</literal> commands, " dongsheng@627: "the counterparts for which are the normal Mercurial <command role=\"hg-cmd" dongsheng@627: "\">hg add</command> and <command role=\"hg-cmd\">hg remove</command> " dongsheng@627: "commands. There is no MQ equivalent of the quilt <literal>edit</literal> " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:5 dongsheng@627: msgid "Advanced uses of Mercurial Queues" dongsheng@627: msgstr "MQ 的高级用法" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:7 dongsheng@627: msgid "" dongsheng@627: "While it's easy to pick up straightforward uses of Mercurial Queues, use of a " dongsheng@627: "little discipline and some of MQ's less frequently used capabilities makes it " dongsheng@627: "possible to work in complicated development environments." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:12 dongsheng@627: msgid "" dongsheng@627: "In this chapter, I will use as an example a technique I have used to manage " dongsheng@627: "the development of an Infiniband device driver for the Linux kernel. The " dongsheng@627: "driver in question is large (at least as drivers go), with 25,000 lines of " dongsheng@627: "code spread across 35 source files. It is maintained by a small team of " dongsheng@627: "developers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:18 dongsheng@627: msgid "" dongsheng@627: "While much of the material in this chapter is specific to Linux, the same " dongsheng@627: "principles apply to any code base for which you're not the primary owner, and " dongsheng@627: "upon which you need to do a lot of development." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:24 dongsheng@627: msgid "The problem of many targets" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:26 dongsheng@627: msgid "" dongsheng@627: "The Linux kernel changes rapidly, and has never been internally stable; " dongsheng@627: "developers frequently make drastic changes between releases. This means that " dongsheng@627: "a version of the driver that works well with a particular released version of " dongsheng@627: "the kernel will not even <emphasis>compile</emphasis> correctly against, " dongsheng@627: "typically, any other version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:33 dongsheng@627: msgid "" dongsheng@627: "To maintain a driver, we have to keep a number of distinct versions of Linux " dongsheng@627: "in mind." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:36 dongsheng@627: msgid "" dongsheng@627: "One target is the main Linux kernel development tree. Maintenance of the code " dongsheng@627: "is in this case partly shared by other developers in the kernel community, " dongsheng@627: "who make <quote>drive-by</quote> modifications to the driver as they develop " dongsheng@627: "and refine kernel subsystems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:42 dongsheng@627: msgid "" dongsheng@627: "We also maintain a number of <quote>backports</quote> to older versions of " dongsheng@627: "the Linux kernel, to support the needs of customers who are running older " dongsheng@627: "Linux distributions that do not incorporate our drivers. (To " dongsheng@627: "<emphasis>backport</emphasis> a piece of code is to modify it to work in an " dongsheng@627: "older version of its target environment than the version it was developed " dongsheng@627: "for.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:50 dongsheng@627: msgid "" dongsheng@627: "Finally, we make software releases on a schedule that is necessarily not " dongsheng@627: "aligned with those used by Linux distributors and kernel developers, so that " dongsheng@627: "we can deliver new features to customers without forcing them to upgrade " dongsheng@627: "their entire kernels or distributions." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:58 dongsheng@627: msgid "Tempting approaches that don't work well" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:60 dongsheng@627: msgid "" dongsheng@627: "There are two <quote>standard</quote> ways to maintain a piece of software " dongsheng@627: "that has to target many different environments." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:64 dongsheng@627: msgid "" dongsheng@627: "The first is to maintain a number of branches, each intended for a single " dongsheng@627: "target. The trouble with this approach is that you must maintain iron " dongsheng@627: "discipline in the flow of changes between repositories. A new feature or bug " dongsheng@627: "fix must start life in a <quote>pristine</quote> repository, then percolate " dongsheng@627: "out to every backport repository. Backport changes are more limited in the " dongsheng@627: "branches they should propagate to; a backport change that is applied to a " dongsheng@627: "branch where it doesn't belong will probably stop the driver from compiling." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:74 dongsheng@627: msgid "" dongsheng@627: "The second is to maintain a single source tree filled with conditional " dongsheng@627: "statements that turn chunks of code on or off depending on the intended " dongsheng@627: "target. Because these <quote>ifdefs</quote> are not allowed in the Linux " dongsheng@627: "kernel tree, a manual or automatic process must be followed to strip them out " dongsheng@627: "and yield a clean tree. A code base maintained in this fashion rapidly " dongsheng@627: "becomes a rat's nest of conditional blocks that are difficult to understand " dongsheng@627: "and maintain." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:83 dongsheng@627: msgid "" dongsheng@627: "Neither of these approaches is well suited to a situation where you don't " dongsheng@627: "<quote>own</quote> the canonical copy of a source tree. In the case of a " dongsheng@627: "Linux driver that is distributed with the standard kernel, Linus's tree " dongsheng@627: "contains the copy of the code that will be treated by the world as " dongsheng@627: "canonical. The upstream version of <quote>my</quote> driver can be modified " dongsheng@627: "by people I don't know, without me even finding out about it until after the " dongsheng@627: "changes show up in Linus's tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:93 dongsheng@627: msgid "" dongsheng@627: "These approaches have the added weakness of making it difficult to generate " dongsheng@627: "well-formed patches to submit upstream." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:97 dongsheng@627: msgid "" dongsheng@627: "In principle, Mercurial Queues seems like a good candidate to manage a " dongsheng@627: "development scenario such as the above. While this is indeed the case, MQ " dongsheng@627: "contains a few added features that make the job more pleasant." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:105 dongsheng@627: msgid "Conditionally applying patches with guards" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:107 dongsheng@627: msgid "" dongsheng@627: "Perhaps the best way to maintain sanity with so many targets is to be able to " dongsheng@627: "choose specific patches to apply for a given situation. MQ provides a " dongsheng@627: "feature called <quote>guards</quote> (which originates with quilt's " dongsheng@627: "<literal>guards</literal> command) that does just this. To start off, let's " dongsheng@627: "create a simple repository for experimenting in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:116 dongsheng@627: msgid "" dongsheng@627: "This gives us a tiny repository that contains two patches that don't have any " dongsheng@627: "dependencies on each other, because they touch different files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:120 dongsheng@627: msgid "" dongsheng@627: "The idea behind conditional application is that you can <quote>tag</quote> a " dongsheng@627: "patch with a <emphasis>guard</emphasis>, which is simply a text string of " dongsheng@627: "your choosing, then tell MQ to select specific guards to use when applying " dongsheng@627: "patches. MQ will then either apply, or skip over, a guarded patch, depending " dongsheng@627: "on the guards that you have selected." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:127 dongsheng@627: msgid "" dongsheng@627: "A patch can have an arbitrary number of guards; each one is " dongsheng@627: "<emphasis>positive</emphasis> (<quote>apply this patch if this guard is " dongsheng@627: "selected</quote>) or <emphasis>negative</emphasis> (<quote>skip this patch if " dongsheng@627: "this guard is selected</quote>). A patch with no guards is always applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:135 dongsheng@627: msgid "Controlling the guards on a patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:137 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qguard</command> command lets you determine " dongsheng@627: "which guards should apply to a patch, or display the guards that are already " dongsheng@627: "in effect. Without any arguments, it displays the guards on the current " dongsheng@627: "topmost patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:144 dongsheng@627: msgid "" dongsheng@627: "To set a positive guard on a patch, prefix the name of the guard with a " dongsheng@627: "<quote><literal>+</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:149 dongsheng@627: msgid "" dongsheng@627: "To set a negative guard on a patch, prefix the name of the guard with a " dongsheng@627: "<quote><literal>-</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:156 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qguard</command> command <emphasis>sets</" dongsheng@627: "emphasis> the guards on a patch; it doesn't <emphasis>modify</emphasis> " dongsheng@627: "them. What this means is that if you run <command role=\"hg-cmd\">hg qguard " dongsheng@627: "+a +b</command> on a patch, then <command role=\"hg-cmd\">hg qguard +c</" dongsheng@627: "command> on the same patch, the <emphasis>only</emphasis> guard that will be " dongsheng@627: "set on it afterwards is <literal>+c</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:165 dongsheng@627: msgid "" dongsheng@627: "Mercurial stores guards in the <filename role=\"special\">series</filename> " dongsheng@627: "file; the form in which they are stored is easy both to understand and to " dongsheng@627: "edit by hand. (In other words, you don't have to use the <command role=\"hg-" dongsheng@627: "ext-mq\">qguard</command> command if you don't want to; it's okay to simply " dongsheng@627: "edit the <filename role=\"special\">series</filename> file.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:177 dongsheng@627: msgid "Selecting the guards to use" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:179 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qselect</command> command determines which " dongsheng@627: "guards are active at a given time. The effect of this is to determine which " dongsheng@627: "patches MQ will apply the next time you run <command role=\"hg-ext-mq" dongsheng@627: "\">qpush</command>. It has no other effect; in particular, it doesn't do " dongsheng@627: "anything to patches that are already applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:186 dongsheng@627: msgid "" dongsheng@627: "With no arguments, the <command role=\"hg-ext-mq\">qselect</command> command " dongsheng@627: "lists the guards currently in effect, one per line of output. Each argument " dongsheng@627: "is treated as the name of a guard to apply." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:193 dongsheng@627: msgid "" dongsheng@627: "In case you're interested, the currently selected guards are stored in the " dongsheng@627: "<filename role=\"special\">guards</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:198 dongsheng@627: msgid "" dongsheng@627: "We can see the effect the selected guards have when we run <command role=\"hg-" dongsheng@627: "ext-mq\">qpush</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:203 dongsheng@627: msgid "" dongsheng@627: "A guard cannot start with a <quote><literal>+</literal></quote> or " dongsheng@627: "<quote><literal>-</literal></quote> character. The name of a guard must not " dongsheng@627: "contain white space, but most other characters are acceptable. If you try to " dongsheng@627: "use a guard with an invalid name, MQ will complain:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:212 dongsheng@627: msgid "Changing the selected guards changes the patches that are applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:217 dongsheng@627: msgid "" dongsheng@627: "You can see in the example below that negative guards take precedence over " dongsheng@627: "positive guards." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:224 dongsheng@627: msgid "MQ's rules for applying patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:226 dongsheng@627: msgid "" dongsheng@627: "The rules that MQ uses when deciding whether to apply a patch are as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:229 dongsheng@627: msgid "A patch that has no guards is always applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:232 dongsheng@627: msgid "" dongsheng@627: "If the patch has any negative guard that matches any currently selected " dongsheng@627: "guard, the patch is skipped." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:235 dongsheng@627: msgid "" dongsheng@627: "If the patch has any positive guard that matches any currently selected " dongsheng@627: "guard, the patch is applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:238 dongsheng@627: msgid "" dongsheng@627: "If the patch has positive or negative guards, but none matches any currently " dongsheng@627: "selected guard, the patch is skipped." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:245 dongsheng@627: msgid "Trimming the work environment" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:247 dongsheng@627: msgid "" dongsheng@627: "In working on the device driver I mentioned earlier, I don't apply the " dongsheng@627: "patches to a normal Linux kernel tree. Instead, I use a repository that " dongsheng@627: "contains only a snapshot of the source files and headers that are relevant to " dongsheng@627: "Infiniband development. This repository is 1% the size of a kernel " dongsheng@627: "repository, so it's easier to work with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:254 dongsheng@627: msgid "" dongsheng@627: "I then choose a <quote>base</quote> version on top of which the patches are " dongsheng@627: "applied. This is a snapshot of the Linux kernel tree as of a revision of my " dongsheng@627: "choosing. When I take the snapshot, I record the changeset ID from the " dongsheng@627: "kernel repository in the commit message. Since the snapshot preserves the " dongsheng@627: "<quote>shape</quote> and content of the relevant parts of the kernel tree, I " dongsheng@627: "can apply my patches on top of either my tiny repository or a normal kernel " dongsheng@627: "tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:263 dongsheng@627: msgid "" dongsheng@627: "Normally, the base tree atop which the patches apply should be a snapshot of " dongsheng@627: "a very recent upstream tree. This best facilitates the development of " dongsheng@627: "patches that can easily be submitted upstream with few or no modifications." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:270 dongsheng@627: msgid "Dividing up the <filename role=\"special\">series</filename> file" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:273 dongsheng@627: msgid "" dongsheng@627: "I categorise the patches in the <filename role=\"special\">series</filename> " dongsheng@627: "file into a number of logical groups. Each section of like patches begins " dongsheng@627: "with a block of comments that describes the purpose of the patches that " dongsheng@627: "follow." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:279 dongsheng@627: msgid "" dongsheng@627: "The sequence of patch groups that I maintain follows. The ordering of these " dongsheng@627: "groups is important; I'll describe why after I introduce the groups." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:283 dongsheng@627: msgid "" dongsheng@627: "The <quote>accepted</quote> group. Patches that the development team has " dongsheng@627: "submitted to the maintainer of the Infiniband subsystem, and which he has " dongsheng@627: "accepted, but which are not present in the snapshot that the tiny repository " dongsheng@627: "is based on. These are <quote>read only</quote> patches, present only to " dongsheng@627: "transform the tree into a similar state as it is in the upstream maintainer's " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:291 dongsheng@627: msgid "" dongsheng@627: "The <quote>rework</quote> group. Patches that I have submitted, but that the " dongsheng@627: "upstream maintainer has requested modifications to before he will accept them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:296 dongsheng@627: msgid "" dongsheng@627: "The <quote>pending</quote> group. Patches that I have not yet submitted to " dongsheng@627: "the upstream maintainer, but which we have finished working on. These will be " dongsheng@627: "<quote>read only</quote> for a while. If the upstream maintainer accepts " dongsheng@627: "them upon submission, I'll move them to the end of the <quote>accepted</" dongsheng@627: "quote> group. If he requests that I modify any, I'll move them to the " dongsheng@627: "beginning of the <quote>rework</quote> group." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:305 dongsheng@627: msgid "" dongsheng@627: "The <quote>in progress</quote> group. Patches that are actively being " dongsheng@627: "developed, and should not be submitted anywhere yet." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:309 dongsheng@627: msgid "" dongsheng@627: "The <quote>backport</quote> group. Patches that adapt the source tree to " dongsheng@627: "older versions of the kernel tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:313 dongsheng@627: msgid "" dongsheng@627: "The <quote>do not ship</quote> group. Patches that for some reason should " dongsheng@627: "never be submitted upstream. For example, one such patch might change " dongsheng@627: "embedded driver identification strings to make it easier to distinguish, in " dongsheng@627: "the field, between an out-of-tree version of the driver and a version shipped " dongsheng@627: "by a distribution vendor." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:321 dongsheng@627: msgid "" dongsheng@627: "Now to return to the reasons for ordering groups of patches in this way. We " dongsheng@627: "would like the lowest patches in the stack to be as stable as possible, so " dongsheng@627: "that we will not need to rework higher patches due to changes in context. " dongsheng@627: "Putting patches that will never be changed first in the <filename role=" dongsheng@627: "\"special\">series</filename> file serves this purpose." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:329 dongsheng@627: msgid "" dongsheng@627: "We would also like the patches that we know we'll need to modify to be " dongsheng@627: "applied on top of a source tree that resembles the upstream tree as closely " dongsheng@627: "as possible. This is why we keep accepted patches around for a while." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:334 dongsheng@627: msgid "" dongsheng@627: "The <quote>backport</quote> and <quote>do not ship</quote> patches float at " dongsheng@627: "the end of the <filename role=\"special\">series</filename> file. The " dongsheng@627: "backport patches must be applied on top of all other patches, and the " dongsheng@627: "<quote>do not ship</quote> patches might as well stay out of harm's way." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:343 dongsheng@627: msgid "Maintaining the patch series" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:345 dongsheng@627: msgid "" dongsheng@627: "In my work, I use a number of guards to control which patches are to be " dongsheng@627: "applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:349 dongsheng@627: msgid "" dongsheng@627: "<quote>Accepted</quote> patches are guarded with <literal>accepted</" dongsheng@627: "literal>. I enable this guard most of the time. When I'm applying the " dongsheng@627: "patches on top of a tree where the patches are already present, I can turn " dongsheng@627: "this patch off, and the patches that follow it will apply cleanly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:356 dongsheng@627: msgid "" dongsheng@627: "Patches that are <quote>finished</quote>, but not yet submitted, have no " dongsheng@627: "guards. If I'm applying the patch stack to a copy of the upstream tree, I " dongsheng@627: "don't need to enable any guards in order to get a reasonably safe source tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:362 dongsheng@627: msgid "" dongsheng@627: "Those patches that need reworking before being resubmitted are guarded with " dongsheng@627: "<literal>rework</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:366 dongsheng@627: msgid "" dongsheng@627: "For those patches that are still under development, I use <literal>devel</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:369 dongsheng@627: msgid "" dongsheng@627: "A backport patch may have several guards, one for each version of the kernel " dongsheng@627: "to which it applies. For example, a patch that backports a piece of code to " dongsheng@627: "2.6.9 will have a <literal>2.6.9</literal> guard." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:374 dongsheng@627: msgid "" dongsheng@627: "This variety of guards gives me considerable flexibility in determining what " dongsheng@627: "kind of source tree I want to end up with. For most situations, the " dongsheng@627: "selection of appropriate guards is automated during the build process, but I " dongsheng@627: "can manually tune the guards to use for less common circumstances." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:381 dongsheng@627: msgid "The art of writing backport patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:383 dongsheng@627: msgid "" dongsheng@627: "Using MQ, writing a backport patch is a simple process. All such a patch has " dongsheng@627: "to do is modify a piece of code that uses a kernel feature not present in the " dongsheng@627: "older version of the kernel, so that the driver continues to work correctly " dongsheng@627: "under that older version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:389 dongsheng@627: msgid "" dongsheng@627: "A useful goal when writing a good backport patch is to make your code look as " dongsheng@627: "if it was written for the older version of the kernel you're targeting. The " dongsheng@627: "less obtrusive the patch, the easier it will be to understand and maintain. " dongsheng@627: "If you're writing a collection of backport patches to avoid the <quote>rat's " dongsheng@627: "nest</quote> effect of lots of <literal>#ifdef</literal>s (hunks of source " dongsheng@627: "code that are only used conditionally) in your code, don't introduce version-" dongsheng@627: "dependent <literal>#ifdef</literal>s into the patches. Instead, write " dongsheng@627: "several patches, each of which makes unconditional changes, and control their " dongsheng@627: "application using guards." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:402 dongsheng@627: msgid "" dongsheng@627: "There are two reasons to divide backport patches into a distinct group, away " dongsheng@627: "from the <quote>regular</quote> patches whose effects they modify. The first " dongsheng@627: "is that intermingling the two makes it more difficult to use a tool like the " dongsheng@627: "<literal role=\"hg-ext\">patchbomb</literal> extension to automate the " dongsheng@627: "process of submitting the patches to an upstream maintainer. The second is " dongsheng@627: "that a backport patch could perturb the context in which a subsequent regular " dongsheng@627: "patch is applied, making it impossible to apply the regular patch cleanly " dongsheng@627: "<emphasis>without</emphasis> the earlier backport patch already being applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:417 dongsheng@627: msgid "Useful tips for developing with MQ" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:420 dongsheng@627: msgid "Organising patches in directories" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:422 dongsheng@627: msgid "" dongsheng@627: "If you're working on a substantial project with MQ, it's not difficult to " dongsheng@627: "accumulate a large number of patches. For example, I have one patch " dongsheng@627: "repository that contains over 250 patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:427 dongsheng@627: msgid "" dongsheng@627: "If you can group these patches into separate logical categories, you can if " dongsheng@627: "you like store them in different directories; MQ has no problems with patch " dongsheng@627: "names that contain path separators." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:434 dongsheng@627: msgid "Viewing the history of a patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:436 dongsheng@627: msgid "" dongsheng@627: "If you're developing a set of patches over a long time, it's a good idea to " dongsheng@627: "maintain them in a repository, as discussed in section <xref linkend=\"sec.mq." dongsheng@627: "repo\"/>. If you do so, you'll quickly discover that using the <command role=" dongsheng@627: "\"hg-cmd\">hg diff</command> command to look at the history of changes to a " dongsheng@627: "patch is unworkable. This is in part because you're looking at the second " dongsheng@627: "derivative of the real code (a diff of a diff), but also because MQ adds " dongsheng@627: "noise to the process by modifying time stamps and directory names when it " dongsheng@627: "updates a patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:448 dongsheng@627: msgid "" dongsheng@627: "However, you can use the <literal role=\"hg-ext\">extdiff</literal> " dongsheng@627: "extension, which is bundled with Mercurial, to turn a diff of two versions of " dongsheng@627: "a patch into something readable. To do this, you will need a third-party " dongsheng@627: "package called <literal role=\"package\">patchutils</literal> <citation>web:" dongsheng@627: "patchutils</citation>. This provides a command named <command>interdiff</" dongsheng@627: "command>, which shows the differences between two diffs as a diff. Used on " dongsheng@627: "two versions of the same diff, it generates a diff that represents the diff " dongsheng@627: "from the first to the second version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:459 dongsheng@627: msgid "" dongsheng@627: "You can enable the <literal role=\"hg-ext\">extdiff</literal> extension in " dongsheng@627: "the usual way, by adding a line to the <literal role=\"rc-extensions" dongsheng@627: "\">extensions</literal> section of your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@630: #. &example.hg-interdiff; dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:465 dongsheng@627: msgid "" dongsheng@627: "The <command>interdiff</command> command expects to be passed the names of " dongsheng@627: "two files, but the <literal role=\"hg-ext\">extdiff</literal> extension " dongsheng@627: "passes the program it runs a pair of directories, each of which can contain " dongsheng@627: "an arbitrary number of files. We thus need a small program that will run " dongsheng@627: "<command>interdiff</command> on each pair of files in these two directories. " dongsheng@627: "This program is available as <filename role=\"special\">hg-interdiff</" dongsheng@627: "filename> in the <filename class=\"directory\">examples</filename> directory " dongsheng@627: "of the source code repository that accompanies this book." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:477 dongsheng@627: msgid "" dongsheng@627: "With the <filename role=\"special\">hg-interdiff</filename> program in your " dongsheng@627: "shell's search path, you can run it as follows, from inside an MQ patch " dongsheng@627: "directory:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:482 dongsheng@627: msgid "" dongsheng@627: "Since you'll probably want to use this long-winded command a lot, you can get " dongsheng@627: "<literal role=\"hg-ext\">hgext</literal> to make it available as a normal " dongsheng@627: "Mercurial command, again by editing your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:489 dongsheng@627: msgid "" dongsheng@627: "This directs <literal role=\"hg-ext\">hgext</literal> to make an " dongsheng@627: "<literal>interdiff</literal> command available, so you can now shorten the " dongsheng@627: "previous invocation of <command role=\"hg-ext-extdiff\">extdiff</command> to " dongsheng@627: "something a little more wieldy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:498 dongsheng@627: msgid "" dongsheng@627: "The <command>interdiff</command> command works well only if the underlying " dongsheng@627: "files against which versions of a patch are generated remain the same. If " dongsheng@627: "you create a patch, modify the underlying files, and then regenerate the " dongsheng@627: "patch, <command>interdiff</command> may not produce useful output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:506 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">extdiff</literal> extension is useful for more " dongsheng@627: "than merely improving the presentation of MQ patches. To read more about it, " dongsheng@627: "go to section <xref linkend=\"sec.hgext.extdiff\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch14-hgext.xml:5 dongsheng@627: msgid "Adding functionality with extensions" dongsheng@627: msgstr "使用扩展增加功能" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch14-hgext.xml:7 dongsheng@627: msgid "" dongsheng@627: "While the core of Mercurial is quite complete from a functionality " dongsheng@627: "standpoint, it's deliberately shorn of fancy features. This approach of " dongsheng@627: "preserving simplicity keeps the software easy to deal with for both " dongsheng@627: "maintainers and users." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch14-hgext.xml:12 dongsheng@627: msgid "" dongsheng@627: "However, Mercurial doesn't box you in with an inflexible command set: you can " dongsheng@627: "add features to it as <emphasis>extensions</emphasis> (sometimes known as " dongsheng@627: "<emphasis>plugins</emphasis>). We've already discussed a few of these " dongsheng@627: "extensions in earlier chapters." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:18 dongsheng@627: msgid "" dongsheng@627: "Section <xref linkend=\"sec.tour-merge.fetch\"/> covers the <literal role=" dongsheng@627: "\"hg-ext\">fetch</literal> extension; this combines pulling new changes and " dongsheng@627: "merging them with local changes into a single command, <command role=\"hg-ext-" dongsheng@627: "fetch\">fetch</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:24 dongsheng@627: msgid "" dongsheng@627: "In chapter <xref linkend=\"chap.hook\"/>, we covered several extensions that " dongsheng@627: "are useful for hook-related functionality: <literal role=\"hg-ext\">acl</" dongsheng@627: "literal> adds access control lists; <literal role=\"hg-ext\">bugzilla</" dongsheng@627: "literal> adds integration with the Bugzilla bug tracking system; and <literal " dongsheng@627: "role=\"hg-ext\">notify</literal> sends notification emails on new changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:33 dongsheng@627: msgid "" dongsheng@627: "The Mercurial Queues patch management extension is so invaluable that it " dongsheng@627: "merits two chapters and an appendix all to itself. Chapter <xref linkend=" dongsheng@627: "\"chap.mq\"/> covers the basics; chapter <xref linkend=\"chap.mq-collab\"/> " dongsheng@627: "discusses advanced topics; and appendix <xref linkend=\"chap.mqref\"/> goes " dongsheng@627: "into detail on each command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch14-hgext.xml:43 dongsheng@627: msgid "" dongsheng@627: "In this chapter, we'll cover some of the other extensions that are available " dongsheng@627: "for Mercurial, and briefly touch on some of the machinery you'll need to know " dongsheng@627: "about if you want to write an extension of your own." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:48 dongsheng@627: msgid "" dongsheng@627: "In section <xref linkend=\"sec.hgext.inotify\"/>, we'll discuss the " dongsheng@627: "possibility of <emphasis>huge</emphasis> performance improvements using the " dongsheng@627: "<literal role=\"hg-ext\">inotify</literal> extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch14-hgext.xml:55 dongsheng@627: msgid "" dongsheng@627: "Improve performance with the <literal role=\"hg-ext\">inotify</literal> " dongsheng@627: "extension" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:58 dongsheng@627: msgid "" dongsheng@627: "Are you interested in having some of the most common Mercurial operations run " dongsheng@627: "as much as a hundred times faster? Read on!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:62 dongsheng@627: msgid "" dongsheng@627: "Mercurial has great performance under normal circumstances. For example, " dongsheng@627: "when you run the <command role=\"hg-cmd\">hg status</command> command, " dongsheng@627: "Mercurial has to scan almost every directory and file in your repository so " dongsheng@627: "that it can display file status. Many other Mercurial commands need to do " dongsheng@627: "the same work behind the scenes; for example, the <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command> command uses the status machinery to avoid doing an expensive " dongsheng@627: "comparison operation on files that obviously haven't changed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:72 dongsheng@627: msgid "" dongsheng@627: "Because obtaining file status is crucial to good performance, the authors of " dongsheng@627: "Mercurial have optimised this code to within an inch of its life. However, " dongsheng@627: "there's no avoiding the fact that when you run <command role=\"hg-cmd\">hg " dongsheng@627: "status</command>, Mercurial is going to have to perform at least one " dongsheng@627: "expensive system call for each managed file to determine whether it's changed " dongsheng@627: "since the last time Mercurial checked. For a sufficiently large repository, " dongsheng@627: "this can take a long time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:82 dongsheng@627: msgid "" dongsheng@627: "To put a number on the magnitude of this effect, I created a repository " dongsheng@627: "containing 150,000 managed files. I timed <command role=\"hg-cmd\">hg " dongsheng@627: "status</command> as taking ten seconds to run, even when <emphasis>none</" dongsheng@627: "emphasis> of those files had been modified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:88 dongsheng@627: msgid "" dongsheng@627: "Many modern operating systems contain a file notification facility. If a " dongsheng@627: "program signs up to an appropriate service, the operating system will notify " dongsheng@627: "it every time a file of interest is created, modified, or deleted. On Linux " dongsheng@627: "systems, the kernel component that does this is called <literal>inotify</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:95 dongsheng@627: msgid "" dongsheng@627: "Mercurial's <literal role=\"hg-ext\">inotify</literal> extension talks to the " dongsheng@627: "kernel's <literal>inotify</literal> component to optimise <command role=\"hg-" dongsheng@627: "cmd\">hg status</command> commands. The extension has two components. A " dongsheng@627: "daemon sits in the background and receives notifications from the " dongsheng@627: "<literal>inotify</literal> subsystem. It also listens for connections from a " dongsheng@627: "regular Mercurial command. The extension modifies Mercurial's behaviour so " dongsheng@627: "that instead of scanning the filesystem, it queries the daemon. Since the " dongsheng@627: "daemon has perfect information about the state of the repository, it can " dongsheng@627: "respond with a result instantaneously, avoiding the need to scan every " dongsheng@627: "directory and file in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:108 dongsheng@627: msgid "" dongsheng@627: "Recall the ten seconds that I measured plain Mercurial as taking to run " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> on a 150,000 file repository. " dongsheng@627: "With the <literal role=\"hg-ext\">inotify</literal> extension enabled, the " dongsheng@627: "time dropped to 0.1 seconds, a factor of <emphasis>one hundred</emphasis> " dongsheng@627: "faster." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:115 dongsheng@627: msgid "Before we continue, please pay attention to some caveats." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:118 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">inotify</literal> extension is Linux-specific. " dongsheng@627: "Because it interfaces directly to the Linux kernel's <literal>inotify</" dongsheng@627: "literal> subsystem, it does not work on other operating systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:123 dongsheng@627: msgid "" dongsheng@627: "It should work on any Linux distribution that was released after early 2005. " dongsheng@627: "Older distributions are likely to have a kernel that lacks <literal>inotify</" dongsheng@627: "literal>, or a version of <literal>glibc</literal> that does not have the " dongsheng@627: "necessary interfacing support." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:130 dongsheng@627: msgid "" dongsheng@627: "Not all filesystems are suitable for use with the <literal role=\"hg-ext" dongsheng@627: "\">inotify</literal> extension. Network filesystems such as NFS are a non-" dongsheng@627: "starter, for example, particularly if you're running Mercurial on several " dongsheng@627: "systems, all mounting the same network filesystem. The kernel's " dongsheng@627: "<literal>inotify</literal> system has no way of knowing about changes made on " dongsheng@627: "another system. Most local filesystems (e.g. ext3, XFS, ReiserFS) should " dongsheng@627: "work fine." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:141 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">inotify</literal> extension is not yet shipped " dongsheng@627: "with Mercurial as of May 2007, so it's a little more involved to set up than " dongsheng@627: "other extensions. But the performance improvement is worth it!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:146 dongsheng@627: msgid "" dongsheng@627: "The extension currently comes in two parts: a set of patches to the Mercurial " dongsheng@627: "source code, and a library of Python bindings to the <literal>inotify</" dongsheng@627: "literal> subsystem." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch14-hgext.xml:150 dongsheng@627: msgid "" dongsheng@627: "There are <emphasis>two</emphasis> Python <literal>inotify</literal> binding " dongsheng@627: "libraries. One of them is called <literal>pyinotify</literal>, and is " dongsheng@627: "packaged by some Linux distributions as <literal>python-inotify</literal>. " dongsheng@627: "This is <emphasis>not</emphasis> the one you'll need, as it is too buggy and " dongsheng@627: "inefficient to be practical." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:157 dongsheng@627: msgid "" dongsheng@627: "To get going, it's best to already have a functioning copy of Mercurial " dongsheng@627: "installed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch14-hgext.xml:160 dongsheng@627: msgid "" dongsheng@627: "If you follow the instructions below, you'll be <emphasis>replacing</" dongsheng@627: "emphasis> and overwriting any existing installation of Mercurial that you " dongsheng@627: "might already have, using the latest <quote>bleeding edge</quote> Mercurial " dongsheng@627: "code. Don't say you weren't warned!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:167 dongsheng@627: msgid "" dongsheng@627: "Clone the Python <literal>inotify</literal> binding repository. Build and " dongsheng@627: "install it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:175 dongsheng@627: msgid "" dongsheng@627: "Clone the <filename class=\"directory\">crew</filename> Mercurial " dongsheng@627: "repository. Clone the <literal role=\"hg-ext\">inotify</literal> patch " dongsheng@627: "repository so that Mercurial Queues will be able to apply patches to your " dongsheng@627: "cope of the <filename class=\"directory\">crew</filename> repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:188 dongsheng@627: msgid "" dongsheng@627: "Make sure that you have the Mercurial Queues extension, <literal role=\"hg-ext" dongsheng@627: "\">mq</literal>, enabled. If you've never used MQ, read section <xref " dongsheng@627: "linkend=\"sec.mq.start\"/> to get started quickly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:194 dongsheng@627: msgid "" dongsheng@627: "Go into the <filename class=\"directory\">inotify</filename> repo, and apply " dongsheng@627: "all of the <literal role=\"hg-ext\">inotify</literal> patches using the " dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</option> option to the " dongsheng@627: "<command role=\"hg-ext-mq\">qpush</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:204 dongsheng@627: msgid "" dongsheng@627: "If you get an error message from <command role=\"hg-ext-mq\">qpush</command>, " dongsheng@627: "you should not continue. Instead, ask for help." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:208 dongsheng@627: msgid "Build and install the patched version of Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:216 dongsheng@627: msgid "" dongsheng@627: "Once you've build a suitably patched version of Mercurial, all you need to do " dongsheng@627: "to enable the <literal role=\"hg-ext\">inotify</literal> extension is add an " dongsheng@627: "entry to your <filename role=\"special\"> /.hgrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:221 dongsheng@627: msgid "" dongsheng@627: "When the <literal role=\"hg-ext\">inotify</literal> extension is enabled, " dongsheng@627: "Mercurial will automatically and transparently start the status daemon the " dongsheng@627: "first time you run a command that needs status in a repository. It runs one " dongsheng@627: "status daemon per repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:227 dongsheng@627: msgid "" dongsheng@627: "The status daemon is started silently, and runs in the background. If you " dongsheng@627: "look at a list of running processes after you've enabled the <literal role=" dongsheng@627: "\"hg-ext\">inotify</literal> extension and run a few commands in different " dongsheng@627: "repositories, you'll thus see a few <literal>hg</literal> processes sitting " dongsheng@627: "around, waiting for updates from the kernel and queries from Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:235 dongsheng@627: msgid "" dongsheng@627: "The first time you run a Mercurial command in a repository when you have the " dongsheng@627: "<literal role=\"hg-ext\">inotify</literal> extension enabled, it will run " dongsheng@627: "with about the same performance as a normal Mercurial command. This is " dongsheng@627: "because the status daemon needs to perform a normal status scan so that it " dongsheng@627: "has a baseline against which to apply later updates from the kernel. " dongsheng@627: "However, <emphasis>every</emphasis> subsequent command that does any kind of " dongsheng@627: "status check should be noticeably faster on repositories of even fairly " dongsheng@627: "modest size. Better yet, the bigger your repository is, the greater a " dongsheng@627: "performance advantage you'll see. The <literal role=\"hg-ext\">inotify</" dongsheng@627: "literal> daemon makes status operations almost instantaneous on repositories " dongsheng@627: "of all sizes!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:249 dongsheng@627: msgid "" dongsheng@627: "If you like, you can manually start a status daemon using the <command role=" dongsheng@627: "\"hg-ext-inotify\">inserve</command> command. This gives you slightly finer " dongsheng@627: "control over how the daemon ought to run. This command will of course only " dongsheng@627: "be available when the <literal role=\"hg-ext\">inotify</literal> extension is " dongsheng@627: "enabled." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:256 dongsheng@627: msgid "" dongsheng@627: "When you're using the <literal role=\"hg-ext\">inotify</literal> extension, " dongsheng@627: "you should notice <emphasis>no difference at all</emphasis> in Mercurial's " dongsheng@627: "behaviour, with the sole exception of status-related commands running a whole " dongsheng@627: "lot faster than they used to. You should specifically expect that commands " dongsheng@627: "will not print different output; neither should they give different results. " dongsheng@627: "If either of these situations occurs, please report a bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch14-hgext.xml:267 dongsheng@627: msgid "" dongsheng@627: "Flexible diff support with the <literal role=\"hg-ext\">extdiff</literal> " dongsheng@627: "extension" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:270 dongsheng@627: msgid "" dongsheng@627: "Mercurial's built-in <command role=\"hg-cmd\">hg diff</command> command " dongsheng@627: "outputs plaintext unified diffs." dongsheng@627: msgstr "" dongsheng@627: "Mercurial 内置命令 <command role=\"hg-cmd\">hg diff</command> 的输出与统一差异" dongsheng@627: "不同。" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:275 dongsheng@627: msgid "" dongsheng@627: "If you would like to use an external tool to display modifications, you'll " dongsheng@627: "want to use the <literal role=\"hg-ext\">extdiff</literal> extension. This " dongsheng@627: "will let you use, for example, a graphical diff tool." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:280 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">extdiff</literal> extension is bundled with " dongsheng@627: "Mercurial, so it's easy to set up. In the <literal role=\"rc-extensions" dongsheng@627: "\">extensions</literal> section of your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>, simply add a one-line entry to enable the extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:286 dongsheng@627: msgid "" dongsheng@627: "This introduces a command named <command role=\"hg-ext-extdiff\">extdiff</" dongsheng@627: "command>, which by default uses your system's <command>diff</command> command " dongsheng@627: "to generate a unified diff in the same form as the built-in <command role=" dongsheng@627: "\"hg-cmd\">hg diff</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:294 dongsheng@627: msgid "" dongsheng@627: "The result won't be exactly the same as with the built-in <command role=\"hg-" dongsheng@627: "cmd\">hg diff</command> variations, because the output of <command>diff</" dongsheng@627: "command> varies from one system to another, even when passed the same options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:299 dongsheng@627: msgid "" dongsheng@627: "As the <quote><literal>making snapshot</literal></quote> lines of output " dongsheng@627: "above imply, the <command role=\"hg-ext-extdiff\">extdiff</command> command " dongsheng@627: "works by creating two snapshots of your source tree. The first snapshot is " dongsheng@627: "of the source revision; the second, of the target revision or working " dongsheng@627: "directory. The <command role=\"hg-ext-extdiff\">extdiff</command> command " dongsheng@627: "generates these snapshots in a temporary directory, passes the name of each " dongsheng@627: "directory to an external diff viewer, then deletes the temporary directory. " dongsheng@627: "For efficiency, it only snapshots the directories and files that have changed " dongsheng@627: "between the two revisions." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:312 dongsheng@627: msgid "" dongsheng@627: "Snapshot directory names have the same base name as your repository. If your " dongsheng@627: "repository path is <filename class=\"directory\">/quux/bar/foo</filename>, " dongsheng@627: "then <filename class=\"directory\">foo</filename> will be the name of each " dongsheng@627: "snapshot directory. Each snapshot directory name has its changeset ID " dongsheng@627: "appended, if appropriate. If a snapshot is of revision " dongsheng@627: "<literal>a631aca1083f</literal>, the directory will be named <filename class=" dongsheng@627: "\"directory\">foo.a631aca1083f</filename>. A snapshot of the working " dongsheng@627: "directory won't have a changeset ID appended, so it would just be <filename " dongsheng@627: "class=\"directory\">foo</filename> in this example. To see what this looks " dongsheng@627: "like in practice, look again at the <command role=\"hg-ext-extdiff\">extdiff</" dongsheng@627: "command> example above. Notice that the diff has the snapshot directory " dongsheng@627: "names embedded in its header." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:328 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-extdiff\">extdiff</command> command accepts two " dongsheng@627: "important options. The <option role=\"hg-ext-extdiff-cmd-extdiff-opt\">hg -p</" dongsheng@627: "option> option lets you choose a program to view differences with, instead of " dongsheng@627: "<command>diff</command>. With the <option role=\"hg-ext-extdiff-cmd-extdiff-" dongsheng@627: "opt\">hg -o</option> option, you can change the options that <command role=" dongsheng@627: "\"hg-ext-extdiff\">extdiff</command> passes to the program (by default, these " dongsheng@627: "options are <quote><literal>-Npru</literal></quote>, which only make sense if " dongsheng@627: "you're running <command>diff</command>). In other respects, the <command " dongsheng@627: "role=\"hg-ext-extdiff\">extdiff</command> command acts similarly to the built-" dongsheng@627: "in <command role=\"hg-cmd\">hg diff</command> command: you use the same " dongsheng@627: "option names, syntax, and arguments to specify the revisions you want, the " dongsheng@627: "files you want, and so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:345 dongsheng@627: msgid "" dongsheng@627: "As an example, here's how to run the normal system <command>diff</command> " dongsheng@627: "command, getting it to generate context diffs (using the <option role=\"cmd-" dongsheng@627: "opt-diff\">-c</option> option) instead of unified diffs, and five lines of " dongsheng@627: "context instead of the default three (passing <literal>5</literal> as the " dongsheng@627: "argument to the <option role=\"cmd-opt-diff\">-C</option> option)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:354 dongsheng@627: msgid "" dongsheng@627: "Launching a visual diff tool is just as easy. Here's how to launch the " dongsheng@627: "<command>kdiff3</command> viewer." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:358 dongsheng@627: msgid "" dongsheng@627: "If your diff viewing command can't deal with directories, you can easily work " dongsheng@627: "around this with a little scripting. For an example of such scripting in " dongsheng@627: "action with the <literal role=\"hg-ext\">mq</literal> extension and the " dongsheng@627: "<command>interdiff</command> command, see section <xref linkend=\"mq-collab." dongsheng@627: "tips.interdiff\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch14-hgext.xml:366 dongsheng@627: msgid "Defining command aliases" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:368 dongsheng@627: msgid "" dongsheng@627: "It can be cumbersome to remember the options to both the <command role=\"hg-" dongsheng@627: "ext-extdiff\">extdiff</command> command and the diff viewer you want to use, " dongsheng@627: "so the <literal role=\"hg-ext\">extdiff</literal> extension lets you define " dongsheng@627: "<emphasis>new</emphasis> commands that will invoke your diff viewer with " dongsheng@627: "exactly the right options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:375 dongsheng@627: msgid "" dongsheng@627: "All you need to do is edit your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>, and add a section named <literal role=\"rc-extdiff\">extdiff</" dongsheng@627: "literal>. Inside this section, you can define multiple commands. Here's how " dongsheng@627: "to add a <literal>kdiff3</literal> command. Once you've defined this, you " dongsheng@627: "can type <quote><literal>hg kdiff3</literal></quote> and the <literal role=" dongsheng@627: "\"hg-ext\">extdiff</literal> extension will run <command>kdiff3</command> for " dongsheng@627: "you." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:384 dongsheng@627: msgid "" dongsheng@627: "If you leave the right hand side of the definition empty, as above, the " dongsheng@627: "<literal role=\"hg-ext\">extdiff</literal> extension uses the name of the " dongsheng@627: "command you defined as the name of the external program to run. But these " dongsheng@627: "names don't have to be the same. Here, we define a command named " dongsheng@627: "<quote><literal>hg wibble</literal></quote>, which runs <command>kdiff3</" dongsheng@627: "command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:393 dongsheng@627: msgid "" dongsheng@627: "You can also specify the default options that you want to invoke your diff " dongsheng@627: "viewing program with. The prefix to use is <quote><literal>opts.</literal></" dongsheng@627: "quote>, followed by the name of the command to which the options apply. This " dongsheng@627: "example defines a <quote><literal>hg vimdiff</literal></quote> command that " dongsheng@627: "runs the <command>vim</command> editor's <literal>DirDiff</literal> extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch14-hgext.xml:406 dongsheng@627: msgid "" dongsheng@627: "Cherrypicking changes with the <literal role=\"hg-ext\">transplant</literal> " dongsheng@627: "extension" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:409 dongsheng@627: msgid "Need to have a long chat with Brendan about this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch14-hgext.xml:413 dongsheng@627: msgid "" dongsheng@627: "Send changes via email with the <literal role=\"hg-ext\">patchbomb</literal> " dongsheng@627: "extension" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:416 dongsheng@627: msgid "" dongsheng@627: "Many projects have a culture of <quote>change review</quote>, in which people " dongsheng@627: "send their modifications to a mailing list for others to read and comment on " dongsheng@627: "before they commit the final version to a shared repository. Some projects " dongsheng@627: "have people who act as gatekeepers; they apply changes from other people to a " dongsheng@627: "repository to which those others don't have access." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:424 dongsheng@627: msgid "" dongsheng@627: "Mercurial makes it easy to send changes over email for review or application, " dongsheng@627: "via its <literal role=\"hg-ext\">patchbomb</literal> extension. The " dongsheng@627: "extension is so named because changes are formatted as patches, and it's " dongsheng@627: "usual to send one changeset per email message. Sending a long series of " dongsheng@627: "changes by email is thus much like <quote>bombing</quote> the recipient's " dongsheng@627: "inbox, hence <quote>patchbomb</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:432 dongsheng@627: msgid "" dongsheng@627: "As usual, the basic configuration of the <literal role=\"hg-ext\">patchbomb</" dongsheng@627: "literal> extension takes just one or two lines in your <filename role=" dongsheng@627: "\"special\"> /.hgrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:437 dongsheng@627: msgid "" dongsheng@627: "Once you've enabled the extension, you will have a new command available, " dongsheng@627: "named <command role=\"hg-ext-patchbomb\">email</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:441 dongsheng@627: msgid "" dongsheng@627: "The safest and best way to invoke the <command role=\"hg-ext-patchbomb" dongsheng@627: "\">email</command> command is to <emphasis>always</emphasis> run it first " dongsheng@627: "with the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -n</option> " dongsheng@627: "option. This will show you what the command <emphasis>would</emphasis> send, " dongsheng@627: "without actually sending anything. Once you've had a quick glance over the " dongsheng@627: "changes and verified that you are sending the right ones, you can rerun the " dongsheng@627: "same command, with the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -n</" dongsheng@627: "option> option removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:452 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-patchbomb\">email</command> command accepts the " dongsheng@627: "same kind of revision syntax as every other Mercurial command. For example, " dongsheng@627: "this command will send every revision between 7 and <literal>tip</literal>, " dongsheng@627: "inclusive." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:457 dongsheng@627: msgid "" dongsheng@627: "You can also specify a <emphasis>repository</emphasis> to compare with. If " dongsheng@627: "you provide a repository but no revisions, the <command role=\"hg-ext-" dongsheng@627: "patchbomb\">email</command> command will send all revisions in the local " dongsheng@627: "repository that are not present in the remote repository. If you " dongsheng@627: "additionally specify revisions or a branch name (the latter using the <option " dongsheng@627: "role=\"hg-ext-patchbomb-cmd-email-opt\">hg -b</option> option), this will " dongsheng@627: "constrain the revisions sent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:466 dongsheng@627: msgid "" dongsheng@627: "It's perfectly safe to run the <command role=\"hg-ext-patchbomb\">email</" dongsheng@627: "command> command without the names of the people you want to send to: if you " dongsheng@627: "do this, it will just prompt you for those values interactively. (If you're " dongsheng@627: "using a Linux or Unix-like system, you should have enhanced " dongsheng@627: "<literal>readline</literal>-style editing capabilities when entering those " dongsheng@627: "headers, too, which is useful.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:474 dongsheng@627: msgid "" dongsheng@627: "When you are sending just one revision, the <command role=\"hg-ext-patchbomb" dongsheng@627: "\">email</command> command will by default use the first line of the " dongsheng@627: "changeset description as the subject of the single email message it sends." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:479 dongsheng@627: msgid "" dongsheng@627: "If you send multiple revisions, the <command role=\"hg-ext-patchbomb\">email</" dongsheng@627: "command> command will usually send one message per changeset. It will " dongsheng@627: "preface the series with an introductory message, in which you should describe " dongsheng@627: "the purpose of the series of changes you're sending." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch14-hgext.xml:486 dongsheng@627: msgid "Changing the behaviour of patchbombs" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:488 dongsheng@627: msgid "" dongsheng@627: "Not every project has exactly the same conventions for sending changes in " dongsheng@627: "email; the <literal role=\"hg-ext\">patchbomb</literal> extension tries to " dongsheng@627: "accommodate a number of variations through command line options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:494 dongsheng@627: msgid "" dongsheng@627: "You can write a subject for the introductory message on the command line " dongsheng@627: "using the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -s</option> " dongsheng@627: "option. This takes one argument, the text of the subject to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:500 dongsheng@627: msgid "" dongsheng@627: "To change the email address from which the messages originate, use the " dongsheng@627: "<option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -f</option> option. This " dongsheng@627: "takes one argument, the email address to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:506 dongsheng@627: msgid "" dongsheng@627: "The default behaviour is to send unified diffs (see section <xref linkend=" dongsheng@627: "\"sec.mq.patch\"/> for a description of the format), one per message. You " dongsheng@627: "can send a binary bundle instead with the <option role=\"hg-ext-patchbomb-cmd-" dongsheng@627: "email-opt\">hg -b</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:514 dongsheng@627: msgid "" dongsheng@627: "Unified diffs are normally prefaced with a metadata header. You can omit " dongsheng@627: "this, and send unadorned diffs, with the <option role=\"hg-ext-patchbomb-cmd-" dongsheng@627: "email-opt\">hg --plain</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:520 dongsheng@627: msgid "" dongsheng@627: "Diffs are normally sent <quote>inline</quote>, in the same body part as the " dongsheng@627: "description of a patch. This makes it easiest for the largest number of " dongsheng@627: "readers to quote and respond to parts of a diff, as some mail clients will " dongsheng@627: "only quote the first MIME body part in a message. If you'd prefer to send the " dongsheng@627: "description and the diff in separate body parts, use the <option role=\"hg-" dongsheng@627: "ext-patchbomb-cmd-email-opt\">hg -a</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:530 dongsheng@627: msgid "" dongsheng@627: "Instead of sending mail messages, you can write them to an <literal>mbox</" dongsheng@627: "literal>-format mail folder using the <option role=\"hg-ext-patchbomb-cmd-" dongsheng@627: "email-opt\">hg -m</option> option. That option takes one argument, the name " dongsheng@627: "of the file to write to." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:537 dongsheng@627: msgid "" dongsheng@627: "If you would like to add a <command>diffstat</command>-format summary to each " dongsheng@627: "patch, and one to the introductory message, use the <option role=\"hg-ext-" dongsheng@627: "patchbomb-cmd-email-opt\">hg -d</option> option. The <command>diffstat</" dongsheng@627: "command> command displays a table containing the name of each file patched, " dongsheng@627: "the number of lines affected, and a histogram showing how much each file is " dongsheng@627: "modified. This gives readers a qualitative glance at how complex a patch is." dongsheng@627: msgstr ""

dongsheng@627: # dongsheng@627: # Simplified Chinese translation for hgbook dongsheng@627: # This file is distributed under the same license as the hgbook. dongsheng@627: # dongsheng@627: # Authors: dongsheng@627: # Dongsheng Song , 2009 dongsheng@627: # dongsheng@627: # Update to new pot: dongsheng@627: # msgmerge --update zh.po svnbook.pot dongsheng@627: # dongsheng@627: # Check translation: dongsheng@627: # msgfmt --statistics -c -o zh.mo zh.po dongsheng@627: # dongsheng@627: # Please format your translation before commit: dongsheng@627: # msgcat --sort-by-file --width=80 -o zh_new.po zh.po dongsheng@627: # mv -f zh_new.po zh.po dongsheng@627: # dongsheng@627: # Dictionary: dongsheng@627: # blame 追溯 dongsheng@627: # branch 分支 dongsheng@627: # changes 修改 dongsheng@627: # changeset 修改集 dongsheng@627: # checkout 检出 dongsheng@627: # remove 移除(从版本库删除) dongsheng@627: # delete 删除(只从文件系统删除) dongsheng@627: # patchset 补丁集 dongsheng@627: # pushing to 推到 dongsheng@635: # pulling from 拉自，抓取 dongsheng@627: # rename 改名 dongsheng@627: # repository 版本库 dongsheng@627: # revert 恢复 dongsheng@627: # revision 版本 dongsheng@627: # tag 标签 dongsheng@627: # tip 顶点 dongsheng@627: # undo 撤销 dongsheng@627: # unversioned 未版本控制 dongsheng@627: # versioned 受版本控制 dongsheng@627: # working copy 工作副本 dongsheng@627: # ... dongsheng@627: # dongsheng@627: msgid "" dongsheng@627: msgstr "" dongsheng@627: "Project-Id-Version: hgbook 1.2\n" dongsheng@630: "POT-Creation-Date: 2009-03-12 16:06+0800\n" dongsheng@630: "PO-Revision-Date: 2009-03-12 18:32+0800\n" dongsheng@627: "Last-Translator: \n" dongsheng@627: "Language-Team: Simplified Chinese \n" dongsheng@627: "MIME-Version: 1.0\n" dongsheng@627: "Content-Type: text/plain; charset=UTF-8\n" dongsheng@627: "Content-Transfer-Encoding: 8bit\n" dongsheng@627: "X-Poedit-Language: Chinese\n" dongsheng@627: "X-Poedit-Country: CHINA\n" dongsheng@627: "X-Poedit-SourceCharset: utf-8\n" dongsheng@627: dongsheng@627: #. type: Content of: dongsheng@627: #: ../en/00book.xml:41 dongsheng@627: msgid "Mercurial: The Definitive Guide" dongsheng@627: msgstr "Mercurial 权威指南" dongsheng@627: dongsheng@627: #. type: Content of: <book><subtitle> dongsheng@627: #: ../en/00book.xml:46 dongsheng@627: msgid "Compiled from $rev_id$" dongsheng@627: msgstr "编译自 $rev_id$" dongsheng@627: dongsheng@627: #. type: Content of: <book><bookinfo><authorgroup><author><firstname> dongsheng@627: #: ../en/00book.xml:50 dongsheng@627: msgid "Bryan" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><bookinfo><authorgroup><author><surname> dongsheng@627: #: ../en/00book.xml:51 dongsheng@627: msgid "O'Sullivan" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><bookinfo> dongsheng@627: #: ../en/00book.xml:55 dongsheng@627: msgid "" dongsheng@627: "<editor> <firstname>Mike</firstname> <surname>Loukides</surname> </editor> " dongsheng@627: "<copyright> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</" dongsheng@627: "year> <holder>Bryan O'Sullivan</holder> </copyright>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><title> dongsheng@627: #: ../en/appA-cmdref.xml:4 dongsheng@627: msgid "Command reference" dongsheng@627: msgstr "命令参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appA-cmdref.xml:6 dongsheng@627: msgid "" dongsheng@627: "\\cmdref{add}{add files at the next commit} \\optref{add}{I}{include} \\optref" dongsheng@627: "{add}{X}{exclude} \\optref{add}{n}{dry-run}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appA-cmdref.xml:11 dongsheng@627: msgid "\\cmdref{diff}{print changes in history or working directory}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appA-cmdref.xml:13 dongsheng@627: msgid "" dongsheng@627: "Show differences between revisions for the specified files or directories, " dongsheng@627: "using the unified diff format. For a description of the unified diff format, " dongsheng@627: "see section <xref linkend=\"sec.mq.patch\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appA-cmdref.xml:17 dongsheng@627: msgid "" dongsheng@627: "By default, this command does not print diffs for files that Mercurial " dongsheng@627: "considers to contain binary data. To control this behaviour, see the <option " dongsheng@627: "role=\"hg-opt-diff\">-a</option> and <option role=\"hg-opt-diff\">--git</" dongsheng@627: "option> options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><title> dongsheng@627: #: ../en/appA-cmdref.xml:22 dongsheng@627: msgid "Options" dongsheng@627: msgstr "选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:24 dongsheng@627: msgid "\\loptref{diff}{nodates}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:26 dongsheng@627: msgid "Omit date and time information when printing diff headers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:28 dongsheng@627: msgid "\\optref{diff}{B}{ignore-blank-lines}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:30 dongsheng@627: msgid "" dongsheng@627: "Do not print changes that only insert or delete blank lines. A line that " dongsheng@627: "contains only whitespace is not considered blank." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:34 dongsheng@627: msgid "\\optref{diff}{I}{include}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:37 dongsheng@627: msgid "Include files and directories whose names match the given patterns." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:40 dongsheng@627: msgid "\\optref{diff}{X}{exclude}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:43 dongsheng@627: msgid "Exclude files and directories whose names match the given patterns." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:46 dongsheng@627: msgid "\\optref{diff}{a}{text}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:49 dongsheng@627: msgid "" dongsheng@627: "If this option is not specified, <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "will refuse to print diffs for files that it detects as binary. Specifying " dongsheng@627: "<option role=\"hg-opt-diff\">-a</option> forces <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command> to treat all files as text, and generate diffs for all of them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:55 dongsheng@627: msgid "" dongsheng@627: "This option is useful for files that are <quote>mostly text</quote> but have " dongsheng@627: "a few embedded NUL characters. If you use it on files that contain a lot of " dongsheng@627: "binary data, its output will be incomprehensible." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:60 dongsheng@627: msgid "\\optref{diff}{b}{ignore-space-change}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:63 dongsheng@627: msgid "" dongsheng@627: "Do not print a line if the only change to that line is in the amount of white " dongsheng@627: "space it contains." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:67 dongsheng@627: msgid "\\optref{diff}{g}{git}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:70 dongsheng@627: msgid "" dongsheng@627: "Print <command>git</command>-compatible diffs. XXX reference a format " dongsheng@627: "description." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:74 dongsheng@627: msgid "\\optref{diff}{p}{show-function}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:77 dongsheng@627: msgid "" dongsheng@627: "Display the name of the enclosing function in a hunk header, using a simple " dongsheng@627: "heuristic. This functionality is enabled by default, so the <option role=" dongsheng@627: "\"hg-opt-diff\">-p</option> option has no effect unless you change the value " dongsheng@627: "of the <envar role=\"rc-item-diff\">showfunc</envar> config item, as in the " dongsheng@627: "following example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:84 dongsheng@627: msgid "\\optref{diff}{r}{rev}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:87 dongsheng@627: msgid "" dongsheng@627: "Specify one or more revisions to compare. The <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command> command accepts up to two <option role=\"hg-opt-diff\">-r</" dongsheng@627: "option> options to specify the revisions to compare." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:93 dongsheng@627: msgid "" dongsheng@627: "Display the differences between the parent revision of the working directory " dongsheng@627: "and the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:97 dongsheng@627: msgid "" dongsheng@627: "Display the differences between the specified changeset and the working " dongsheng@627: "directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:101 dongsheng@627: msgid "Display the differences between the two specified changesets." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:105 dongsheng@627: msgid "" dongsheng@627: "You can specify two revisions using either two <option role=\"hg-opt-diff\">-" dongsheng@627: "r</option> options or revision range notation. For example, the two revision " dongsheng@627: "specifications below are equivalent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:112 dongsheng@627: msgid "" dongsheng@627: "When you provide two revisions, Mercurial treats the order of those revisions " dongsheng@627: "as significant. Thus, <command role=\"hg-cmd\">hg diff -r10:20</command> " dongsheng@627: "will produce a diff that will transform files from their contents as of " dongsheng@627: "revision 10 to their contents as of revision 20, while <command role=\"hg-cmd" dongsheng@627: "\">hg diff -r20:10</command> means the opposite: the diff that will transform " dongsheng@627: "files from their revision 20 contents to their revision 10 contents. You " dongsheng@627: "cannot reverse the ordering in this way if you are diffing against the " dongsheng@627: "working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:122 dongsheng@627: msgid "\\optref{diff}{w}{ignore-all-space}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:125 dongsheng@627: msgid "\\cmdref{version}{print version and copyright information}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><para> dongsheng@627: #: ../en/appA-cmdref.xml:128 dongsheng@627: msgid "" dongsheng@627: "This command displays the version of Mercurial you are running, and its " dongsheng@627: "copyright license. There are four kinds of version string that you may see." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:133 dongsheng@627: msgid "" dongsheng@627: "The string <quote><literal>unknown</literal></quote>. This version of " dongsheng@627: "Mercurial was not built in a Mercurial repository, and cannot determine its " dongsheng@627: "own version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:138 dongsheng@627: msgid "" dongsheng@627: "A short numeric string, such as <quote><literal>1.1</literal></quote>. This " dongsheng@627: "is a build of a revision of Mercurial that was identified by a specific tag " dongsheng@627: "in the repository where it was built. (This doesn't necessarily mean that " dongsheng@627: "you're running an official release; someone else could have added that tag to " dongsheng@627: "any revision in the repository where they built Mercurial.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:146 dongsheng@627: msgid "" dongsheng@627: "A hexadecimal string, such as <quote><literal>875489e31abe</literal></" dongsheng@627: "quote>. This is a build of the given revision of Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appA-cmdref.xml:150 dongsheng@627: msgid "" dongsheng@627: "A hexadecimal string followed by a date, such as <quote><literal>875489e31abe" dongsheng@627: "+20070205</literal></quote>. This is a build of the given revision of " dongsheng@627: "Mercurial, where the build repository contained some local changes that had " dongsheng@627: "not been committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><title> dongsheng@627: #: ../en/appA-cmdref.xml:159 dongsheng@627: msgid "Tips and tricks" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><title> dongsheng@627: #: ../en/appA-cmdref.xml:162 dongsheng@627: msgid "" dongsheng@627: "Why do the results of <command role=\"hg-cmd\">hg diff</command> and <command " dongsheng@627: "role=\"hg-cmd\">hg status</command> differ?" dongsheng@627: msgstr "" dongsheng@627: "为什么 <command role=\"hg-cmd\">hg diff</command> 与 <command role=\"hg-cmd" dongsheng@627: "\">hg status</command> 的结果不同 ?" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:164 dongsheng@627: msgid "" dongsheng@627: "When you run the <command role=\"hg-cmd\">hg status</command> command, you'll " dongsheng@627: "see a list of files that Mercurial will record changes for the next time you " dongsheng@627: "perform a commit. If you run the <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "command, you may notice that it prints diffs for only a <emphasis>subset</" dongsheng@627: "emphasis> of the files that <command role=\"hg-cmd\">hg status</command> " dongsheng@627: "listed. There are two possible reasons for this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:171 dongsheng@627: msgid "" dongsheng@627: "The first is that <command role=\"hg-cmd\">hg status</command> prints some " dongsheng@627: "kinds of modifications that <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "doesn't normally display. The <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "command normally outputs unified diffs, which don't have the ability to " dongsheng@627: "represent some changes that Mercurial can track. Most notably, traditional " dongsheng@627: "diffs can't represent a change in whether or not a file is executable, but " dongsheng@627: "Mercurial records this information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:179 dongsheng@627: msgid "" dongsheng@627: "If you use the <option role=\"hg-opt-diff\">--git</option> option to <command " dongsheng@627: "role=\"hg-cmd\">hg diff</command>, it will display <command>git</command>-" dongsheng@627: "compatible diffs that <emphasis>can</emphasis> display this extra information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:184 dongsheng@627: msgid "" dongsheng@627: "The second possible reason that <command role=\"hg-cmd\">hg diff</command> " dongsheng@627: "might be printing diffs for a subset of the files displayed by <command role=" dongsheng@627: "\"hg-cmd\">hg status</command> is that if you invoke it without any " dongsheng@627: "arguments, <command role=\"hg-cmd\">hg diff</command> prints diffs against " dongsheng@627: "the first parent of the working directory. If you have run <command role=" dongsheng@627: "\"hg-cmd\">hg merge</command> to merge two changesets, but you haven't yet " dongsheng@627: "committed the results of the merge, your working directory has two parents " dongsheng@627: "(use <command role=\"hg-cmd\">hg parents</command> to see them). While " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> prints modifications relative to " dongsheng@627: "<emphasis>both</emphasis> parents after an uncommitted merge, <command role=" dongsheng@627: "\"hg-cmd\">hg diff</command> still operates relative only to the first " dongsheng@627: "parent. You can get it to print diffs relative to the second parent by " dongsheng@627: "specifying that parent with the <option role=\"hg-opt-diff\">-r</option> " dongsheng@627: "option. There is no way to print diffs relative to both parents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><title> dongsheng@627: #: ../en/appA-cmdref.xml:200 dongsheng@627: msgid "Generating safe binary diffs" dongsheng@627: msgstr "生成安全的二进制差异" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:202 dongsheng@627: msgid "" dongsheng@627: "If you use the <option role=\"hg-opt-diff\">-a</option> option to force " dongsheng@627: "Mercurial to print diffs of files that are either <quote>mostly text</quote> " dongsheng@627: "or contain lots of binary data, those diffs cannot subsequently be applied by " dongsheng@627: "either Mercurial's <command role=\"hg-cmd\">hg import</command> command or " dongsheng@627: "the system's <command>patch</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect2><sect3><para> dongsheng@627: #: ../en/appA-cmdref.xml:209 dongsheng@627: msgid "" dongsheng@627: "If you want to generate a diff of a binary file that is safe to use as input " dongsheng@627: "for <command role=\"hg-cmd\">hg import</command>, use the <command role=\"hg-" dongsheng@627: "cmd\">hg diff</command>{--git} option when you generate the patch. The " dongsheng@627: "system <command>patch</command> command cannot handle binary patches at all." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><title> dongsheng@627: #: ../en/appB-mq-ref.xml:5 dongsheng@627: msgid "Mercurial Queues reference" dongsheng@627: msgstr "Mercurial 队列参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appB-mq-ref.xml:8 dongsheng@627: msgid "MQ command reference" dongsheng@627: msgstr "MQ 命令参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appB-mq-ref.xml:10 dongsheng@627: msgid "" dongsheng@627: "For an overview of the commands provided by MQ, use the command <command role=" dongsheng@627: "\"hg-cmd\">hg help mq</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:14 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qapplied</command>&emdash;print applied patches" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qapplied</command>&emdash;显示已应用的补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:17 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qapplied</command> command prints the current " dongsheng@627: "stack of applied patches. Patches are printed in oldest-to-newest order, so " dongsheng@627: "the last patch in the list is the <quote>top</quote> patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:24 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qcommit</command>&emdash;commit changes in the " dongsheng@627: "queue repository" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qcommit</command>&emdash;提交队列中的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:27 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qcommit</command> command commits any " dongsheng@627: "outstanding changes in the <filename role=\"special\" class=\"directory\">.hg/" dongsheng@627: "patches</filename> repository. This command only works if the <filename role=" dongsheng@627: "\"special\" class=\"directory\">.hg/patches</filename> directory is a " dongsheng@627: "repository, i.e. you created the directory using <command role=\"hg-cmd\">hg " dongsheng@627: "qinit <option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option></command> or ran " dongsheng@627: "<command role=\"hg-cmd\">hg init</command> in the directory after running " dongsheng@627: "<command role=\"hg-ext-mq\">qinit</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:39 dongsheng@627: msgid "" dongsheng@627: "This command is shorthand for <command role=\"hg-cmd\">hg commit --cwd .hg/" dongsheng@627: "patches</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:42 dongsheng@627: msgid "" dongsheng@627: "\\subsection{<command role=\"hg-ext-mq\">qdelete</command>&emdash;delete a " dongsheng@627: "patch from the <filename role=\"special\">series</filename> file}" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:47 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qdelete</command> command removes the entry " dongsheng@627: "for a patch from the <filename role=\"special\">series</filename> file in the " dongsheng@627: "<filename role=\"special\" class=\"directory\">.hg/patches</filename> " dongsheng@627: "directory. It does not pop the patch if the patch is already applied. By " dongsheng@627: "default, it does not delete the patch file; use the <option role=\"hg-ext-mq-" dongsheng@627: "cmd-qdel-opt\">-f</option> option to do that." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:56 ../en/appB-mq-ref.xml:98 ../en/appB-mq-ref.xml:156 dongsheng@627: #: ../en/appB-mq-ref.xml:196 ../en/appB-mq-ref.xml:263 dongsheng@627: #: ../en/appB-mq-ref.xml:334 ../en/appB-mq-ref.xml:403 dongsheng@627: #: ../en/appB-mq-ref.xml:496 dongsheng@627: msgid "Options:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:58 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qdel-opt\">-f</option>: Delete the patch file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:65 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qdiff</command>&emdash;print a diff of the " dongsheng@627: "topmost applied patch" dongsheng@627: msgstr "" dongsheng@627: "<command role=\"hg-ext-mq\">qdiff</command>&emdash;显示最新应用补丁的差异" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:68 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qdiff</command> command prints a diff of the " dongsheng@627: "topmost applied patch. It is equivalent to <command role=\"hg-cmd\">hg diff -" dongsheng@627: "r-2:-1</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:74 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qfold</command>&emdash;merge (<quote>fold</" dongsheng@627: "quote>) several patches into one" dongsheng@627: msgstr "" dongsheng@627: "<command role=\"hg-ext-mq\">qfold</command>&emdash;将多个补丁合并(<quote>折叠" dongsheng@627: "</quote>)成一个" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:77 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qfold</command> command merges multiple " dongsheng@627: "patches into the topmost applied patch, so that the topmost applied patch " dongsheng@627: "makes the union of all of the changes in the patches in question." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:82 dongsheng@627: msgid "" dongsheng@627: "The patches to fold must not be applied; <command role=\"hg-ext-mq\">qfold</" dongsheng@627: "command> will exit with an error if any is. The order in which patches are " dongsheng@627: "folded is significant; <command role=\"hg-cmd\">hg qfold a b</command> means " dongsheng@627: "<quote>apply the current topmost patch, followed by <literal>a</literal>, " dongsheng@627: "followed by <literal>b</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:90 dongsheng@627: msgid "" dongsheng@627: "The comments from the folded patches are appended to the comments of the " dongsheng@627: "destination patch, with each block of comments separated by three asterisk " dongsheng@627: "(<quote><literal>*</literal></quote>) characters. Use the <option role=\"hg-" dongsheng@627: "ext-mq-cmd-qfold-opt\">-e</option> option to edit the commit message for the " dongsheng@627: "combined patch/changeset after the folding has completed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:100 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qfold-opt\">-e</option>: Edit the commit message " dongsheng@627: "and patch description for the newly folded patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:105 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qfold-opt\">-l</option>: Use the contents of the " dongsheng@627: "given file as the new commit message and patch description for the folded " dongsheng@627: "patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:110 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qfold-opt\">-m</option>: Use the given text as " dongsheng@627: "the new commit message and patch description for the folded patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:118 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qheader</command>&emdash;display the header/" dongsheng@627: "description of a patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qheader</command>&emdash;显示补丁头部描述" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:122 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qheader</command> command prints the header, " dongsheng@627: "or description, of a patch. By default, it prints the header of the topmost " dongsheng@627: "applied patch. Given an argument, it prints the header of the named patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:129 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qimport</command>&emdash;import a third-party " dongsheng@627: "patch into the queue" dongsheng@627: msgstr "" dongsheng@627: "<command role=\"hg-ext-mq\">qimport</command>&emdash;将第三方补丁导入队列" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:132 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qimport</command> command adds an entry for " dongsheng@627: "an external patch to the <filename role=\"special\">series</filename> file, " dongsheng@627: "and copies the patch into the <filename role=\"special\" class=\"directory\">." dongsheng@627: "hg/patches</filename> directory. It adds the entry immediately after the " dongsheng@627: "topmost applied patch, but does not push the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:140 dongsheng@627: msgid "" dongsheng@627: "If the <filename role=\"special\" class=\"directory\">.hg/patches</filename> " dongsheng@627: "directory is a repository, <command role=\"hg-ext-mq\">qimport</command> " dongsheng@627: "automatically does an <command role=\"hg-cmd\">hg add</command> of the " dongsheng@627: "imported patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:148 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qinit</command>&emdash;prepare a repository to " dongsheng@627: "work with MQ" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qinit</command>&emdash;为使用 MQ 配置版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:151 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qinit</command> command prepares a repository " dongsheng@627: "to work with MQ. It creates a directory called <filename role=\"special\" " dongsheng@627: "class=\"directory\">.hg/patches</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:158 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option>: Create <filename role=" dongsheng@627: "\"special\" class=\"directory\">.hg/patches</filename> as a repository in its " dongsheng@627: "own right. Also creates a <filename role=\"special\">.hgignore</filename> " dongsheng@627: "file that will ignore the <filename role=\"special\">status</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:168 dongsheng@627: msgid "" dongsheng@627: "When the <filename role=\"special\" class=\"directory\">.hg/patches</" dongsheng@627: "filename> directory is a repository, the <command role=\"hg-ext-mq\">qimport</" dongsheng@627: "command> and <command role=\"hg-ext-mq\">qnew</command> commands " dongsheng@627: "automatically <command role=\"hg-cmd\">hg add</command> new patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:177 dongsheng@627: msgid "<command role=\"hg-ext-mq\">qnew</command>&emdash;create a new patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qnew</command>&emdash;创建新补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:180 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qnew</command> command creates a new patch. " dongsheng@627: "It takes one mandatory argument, the name to use for the patch file. The " dongsheng@627: "newly created patch is created empty by default. It is added to the " dongsheng@627: "<filename role=\"special\">series</filename> file after the current topmost " dongsheng@627: "applied patch, and is immediately pushed on top of that patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:188 dongsheng@627: msgid "" dongsheng@627: "If <command role=\"hg-ext-mq\">qnew</command> finds modified files in the " dongsheng@627: "working directory, it will refuse to create a new patch unless the <option " dongsheng@627: "role=\"hg-ext-mq-cmd-qnew-opt\">-f</option> option is used (see below). This " dongsheng@627: "behaviour allows you to <command role=\"hg-ext-mq\">qrefresh</command> your " dongsheng@627: "topmost applied patch before you apply a new patch on top of it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:198 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qnew-opt\">-f</option>: Create a new patch if " dongsheng@627: "the contents of the working directory are modified. Any outstanding " dongsheng@627: "modifications are added to the newly created patch, so after this command " dongsheng@627: "completes, the working directory will no longer be modified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:205 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qnew-opt\">-m</option>: Use the given text as " dongsheng@627: "the commit message. This text will be stored at the beginning of the patch " dongsheng@627: "file, before the patch data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:214 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qnext</command>&emdash;print the name of the next " dongsheng@627: "patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qnext</command>&emdash;显示下个补丁的名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:217 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qnext</command> command prints the name name " dongsheng@627: "of the next patch in the <filename role=\"special\">series</filename> file " dongsheng@627: "after the topmost applied patch. This patch will become the topmost applied " dongsheng@627: "patch if you run <command role=\"hg-ext-mq\">qpush</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:226 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qpop</command>&emdash;pop patches off the stack" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qpop</command>&emdash;删除堆栈顶部的补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:229 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpop</command> command removes applied " dongsheng@627: "patches from the top of the stack of applied patches. By default, it removes " dongsheng@627: "only one patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:233 dongsheng@627: msgid "" dongsheng@627: "This command removes the changesets that represent the popped patches from " dongsheng@627: "the repository, and updates the working directory to undo the effects of the " dongsheng@627: "patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:237 dongsheng@627: msgid "" dongsheng@627: "This command takes an optional argument, which it uses as the name or index " dongsheng@627: "of the patch to pop to. If given a name, it will pop patches until the named " dongsheng@627: "patch is the topmost applied patch. If given a number, <command role=\"hg-" dongsheng@627: "ext-mq\">qpop</command> treats the number as an index into the entries in the " dongsheng@627: "series file, counting from zero (empty lines and lines containing only " dongsheng@627: "comments do not count). It pops patches until the patch identified by the " dongsheng@627: "given index is the topmost applied patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:247 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpop</command> command does not read or write " dongsheng@627: "patches or the <filename role=\"special\">series</filename> file. It is thus " dongsheng@627: "safe to <command role=\"hg-ext-mq\">qpop</command> a patch that you have " dongsheng@627: "removed from the <filename role=\"special\">series</filename> file, or a " dongsheng@627: "patch that you have renamed or deleted entirely. In the latter two cases, " dongsheng@627: "use the name of the patch as it was when you applied it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:256 dongsheng@627: msgid "" dongsheng@627: "By default, the <command role=\"hg-ext-mq\">qpop</command> command will not " dongsheng@627: "pop any patches if the working directory has been modified. You can override " dongsheng@627: "this behaviour using the <option role=\"hg-ext-mq-cmd-qpop-opt\">-f</option> " dongsheng@627: "option, which reverts all modifications in the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:265 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpop-opt\">-a</option>: Pop all applied " dongsheng@627: "patches. This returns the repository to its state before you applied any " dongsheng@627: "patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:270 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpop-opt\">-f</option>: Forcibly revert any " dongsheng@627: "modifications to the working directory when popping." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:275 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpop-opt\">-n</option>: Pop a patch from the " dongsheng@627: "named queue." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:280 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpop</command> command removes one line from " dongsheng@627: "the end of the <filename role=\"special\">status</filename> file for each " dongsheng@627: "patch that it pops." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:287 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qprev</command>&emdash;print the name of the " dongsheng@627: "previous patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qprev</command>&emdash;显示上个补丁的名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:290 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qprev</command> command prints the name of " dongsheng@627: "the patch in the <filename role=\"special\">series</filename> file that comes " dongsheng@627: "before the topmost applied patch. This will become the topmost applied patch " dongsheng@627: "if you run <command role=\"hg-ext-mq\">qpop</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:299 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qpush</command>&emdash;push patches onto the stack" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qpush</command>&emdash;增加补丁到堆栈" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:302 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpush</command> command adds patches onto the " dongsheng@627: "applied stack. By default, it adds only one patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:306 dongsheng@627: msgid "" dongsheng@627: "This command creates a new changeset to represent each applied patch, and " dongsheng@627: "updates the working directory to apply the effects of the patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:310 dongsheng@627: msgid "The default data used when creating a changeset are as follows:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:313 dongsheng@627: msgid "" dongsheng@627: "The commit date and time zone are the current date and time zone. Because " dongsheng@627: "these data are used to compute the identity of a changeset, this means that " dongsheng@627: "if you <command role=\"hg-ext-mq\">qpop</command> a patch and <command role=" dongsheng@627: "\"hg-ext-mq\">qpush</command> it again, the changeset that you push will have " dongsheng@627: "a different identity than the changeset you popped." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:321 dongsheng@627: msgid "" dongsheng@627: "The author is the same as the default used by the <command role=\"hg-cmd\">hg " dongsheng@627: "commit</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:325 dongsheng@627: msgid "" dongsheng@627: "The commit message is any text from the patch file that comes before the " dongsheng@627: "first diff header. If there is no such text, a default commit message is " dongsheng@627: "used that identifies the name of the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:330 dongsheng@627: msgid "" dongsheng@627: "If a patch contains a Mercurial patch header (XXX add link), the information " dongsheng@627: "in the patch header overrides these defaults." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:336 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">-a</option>: Push all unapplied " dongsheng@627: "patches from the <filename role=\"special\">series</filename> file until " dongsheng@627: "there are none left to push." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:342 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">-l</option>: Add the name of the " dongsheng@627: "patch to the end of the commit message." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:346 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">-m</option>: If a patch fails to " dongsheng@627: "apply cleanly, use the entry for the patch in another saved queue to compute " dongsheng@627: "the parameters for a three-way merge, and perform a three-way merge using the " dongsheng@627: "normal Mercurial merge machinery. Use the resolution of the merge as the new " dongsheng@627: "patch content." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:354 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">-n</option>: Use the named queue if " dongsheng@627: "merging while pushing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:359 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpush</command> command reads, but does not " dongsheng@627: "modify, the <filename role=\"special\">series</filename> file. It appends " dongsheng@627: "one line to the <command role=\"hg-cmd\">hg status</command> file for each " dongsheng@627: "patch that it pushes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:367 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qrefresh</command>&emdash;update the topmost " dongsheng@627: "applied patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qrefresh</command>&emdash;更新最新的补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:371 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qrefresh</command> command updates the " dongsheng@627: "topmost applied patch. It modifies the patch, removes the old changeset that " dongsheng@627: "represented the patch, and creates a new changeset to represent the modified " dongsheng@627: "patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:377 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qrefresh</command> command looks for the " dongsheng@627: "following modifications:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:380 dongsheng@627: msgid "" dongsheng@627: "Changes to the commit message, i.e. the text before the first diff header in " dongsheng@627: "the patch file, are reflected in the new changeset that represents the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:385 dongsheng@627: msgid "" dongsheng@627: "Modifications to tracked files in the working directory are added to the " dongsheng@627: "patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:388 dongsheng@627: msgid "" dongsheng@627: "Changes to the files tracked using <command role=\"hg-cmd\">hg add</command>, " dongsheng@627: "<command role=\"hg-cmd\">hg copy</command>, <command role=\"hg-cmd\">hg " dongsheng@627: "remove</command>, or <command role=\"hg-cmd\">hg rename</command>. Added " dongsheng@627: "files and copy and rename destinations are added to the patch, while removed " dongsheng@627: "files and rename sources are removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:397 dongsheng@627: msgid "" dongsheng@627: "Even if <command role=\"hg-ext-mq\">qrefresh</command> detects no changes, it " dongsheng@627: "still recreates the changeset that represents the patch. This causes the " dongsheng@627: "identity of the changeset to differ from the previous changeset that " dongsheng@627: "identified the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:405 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-e</option>: Modify the commit " dongsheng@627: "and patch description, using the preferred text editor." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:410 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-m</option>: Modify the commit " dongsheng@627: "message and patch description, using the given text." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:415 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-l</option>: Modify the commit " dongsheng@627: "message and patch description, using text from the given file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:423 dongsheng@627: msgid "<command role=\"hg-ext-mq\">qrename</command>&emdash;rename a patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qrename</command>&emdash;改名补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:426 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qrename</command> command renames a patch, " dongsheng@627: "and changes the entry for the patch in the <filename role=\"special\">series</" dongsheng@627: "filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:430 dongsheng@627: msgid "" dongsheng@627: "With a single argument, <command role=\"hg-ext-mq\">qrename</command> renames " dongsheng@627: "the topmost applied patch. With two arguments, it renames its first argument " dongsheng@627: "to its second." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:437 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qrestore</command>&emdash;restore saved queue " dongsheng@627: "state" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qrestore</command>&emdash;恢复保存的队列" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:441 dongsheng@627: msgid "XXX No idea what this does." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:445 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qsave</command>&emdash;save current queue state" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qsave</command>&emdash;保存当前的队列状态" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:448 dongsheng@627: msgid "XXX Likewise." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:452 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qseries</command>&emdash;print the entire patch " dongsheng@627: "series" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qseries</command>&emdash;显示补丁序列" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:455 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qseries</command> command prints the entire " dongsheng@627: "patch series from the <filename role=\"special\">series</filename> file. It " dongsheng@627: "prints only patch names, not empty lines or comments. It prints in order " dongsheng@627: "from first to be applied to last." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:463 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qtop</command>&emdash;print the name of the " dongsheng@627: "current patch" dongsheng@627: msgstr "<command role=\"hg-ext-mq\">qtop</command>&emdash;显示当前补丁的名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:466 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qtop</command> prints the name of the topmost " dongsheng@627: "currently applied patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:471 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-ext-mq\">qunapplied</command>&emdash;print patches not yet " dongsheng@627: "applied" dongsheng@627: msgstr "" dongsheng@627: "<command role=\"hg-ext-mq\">qunapplied</command>&emdash;显示尚未应用的补丁" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:475 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qunapplied</command> command prints the names " dongsheng@627: "of patches from the <filename role=\"special\">series</filename> file that " dongsheng@627: "are not yet applied. It prints them in order from the next patch that will " dongsheng@627: "be pushed to the last." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:483 dongsheng@627: msgid "" dongsheng@627: "<command role=\"hg-cmd\">hg strip</command>&emdash;remove a revision and " dongsheng@627: "descendants" dongsheng@627: msgstr "<command role=\"hg-cmd\">hg strip</command>&emdash;删除一个版本及其后继" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:486 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg strip</command> command removes a revision, " dongsheng@627: "and all of its descendants, from the repository. It undoes the effects of " dongsheng@627: "the removed revisions from the repository, and updates the working directory " dongsheng@627: "to the first parent of the removed revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:492 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg strip</command> command saves a backup of the " dongsheng@627: "removed changesets in a bundle, so that they can be reapplied if removed in " dongsheng@627: "error." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:498 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-opt-strip\">-b</option>: Save unrelated changesets that are " dongsheng@627: "intermixed with the stripped changesets in the backup bundle." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:502 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-opt-strip\">-f</option>: If a branch has multiple heads, " dongsheng@627: "remove all heads. XXX This should be renamed, and use <literal>-f</literal> " dongsheng@627: "to strip revs when there are pending changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/appB-mq-ref.xml:507 dongsheng@627: msgid "<option role=\"hg-opt-strip\">-n</option>: Do not save a backup bundle." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appB-mq-ref.xml:514 dongsheng@627: msgid "MQ file reference" dongsheng@627: msgstr "MQ 文件参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:517 dongsheng@627: msgid "The <filename role=\"special\">series</filename> file" dongsheng@627: msgstr "<filename role=\"special\">序列</filename>文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:520 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">series</filename> file contains a list of the " dongsheng@627: "names of all patches that MQ can apply. It is represented as a list of " dongsheng@627: "names, with one name saved per line. Leading and trailing white space in " dongsheng@627: "each line are ignored." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:526 dongsheng@627: msgid "" dongsheng@627: "Lines may contain comments. A comment begins with the <quote><literal>#</" dongsheng@627: "literal></quote> character, and extends to the end of the line. Empty lines, " dongsheng@627: "and lines that contain only comments, are ignored." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:531 dongsheng@627: msgid "" dongsheng@627: "You will often need to edit the <filename role=\"special\">series</filename> " dongsheng@627: "file by hand, hence the support for comments and empty lines noted above. " dongsheng@627: "For example, you can comment out a patch temporarily, and <command role=\"hg-" dongsheng@627: "ext-mq\">qpush</command> will skip over that patch when applying patches. " dongsheng@627: "You can also change the order in which patches are applied by reordering " dongsheng@627: "their entries in the <filename role=\"special\">series</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:540 dongsheng@627: msgid "" dongsheng@627: "Placing the <filename role=\"special\">series</filename> file under revision " dongsheng@627: "control is also supported; it is a good idea to place all of the patches that " dongsheng@627: "it refers to under revision control, as well. If you create a patch " dongsheng@627: "directory using the <option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option> " dongsheng@627: "option to <command role=\"hg-ext-mq\">qinit</command>, this will be done for " dongsheng@627: "you automatically." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><title> dongsheng@627: #: ../en/appB-mq-ref.xml:550 dongsheng@627: msgid "The <filename role=\"special\">status</filename> file" dongsheng@627: msgstr "<filename role=\"special\">状态</filename>文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><sect2><para> dongsheng@627: #: ../en/appB-mq-ref.xml:553 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">status</filename> file contains the names and " dongsheng@627: "changeset hashes of all patches that MQ currently has applied. Unlike the " dongsheng@627: "<filename role=\"special\">series</filename> file, this file is not intended " dongsheng@627: "for editing. You should not place this file under revision control, or " dongsheng@627: "modify it in any way. It is used by MQ strictly for internal book-keeping." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><title> dongsheng@627: #: ../en/appC-srcinstall.xml:5 dongsheng@627: msgid "Installing Mercurial from source" dongsheng@627: msgstr "从源代码安装 Mercurial" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appC-srcinstall.xml:8 dongsheng@627: msgid "On a Unix-like system" dongsheng@627: msgstr "类 Unix 系统" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:10 dongsheng@627: msgid "" dongsheng@627: "If you are using a Unix-like system that has a sufficiently recent version of " dongsheng@627: "Python (2.3 or newer) available, it is easy to install Mercurial from source." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appC-srcinstall.xml:14 dongsheng@627: msgid "" dongsheng@627: "Download a recent source tarball from <ulink url=\"http://www.selenic.com/" dongsheng@627: "mercurial/download\">http://www.selenic.com/mercurial/download</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appC-srcinstall.xml:17 dongsheng@627: msgid "Unpack the tarball:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appC-srcinstall.xml:20 dongsheng@627: msgid "" dongsheng@627: "Go into the source directory and run the installer script. This will build " dongsheng@627: "Mercurial and install it in your home directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:27 dongsheng@627: msgid "" dongsheng@627: "Once the install finishes, Mercurial will be in the <literal>bin</literal> " dongsheng@627: "subdirectory of your home directory. Don't forget to make sure that this " dongsheng@627: "directory is present in your shell's search path." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:32 dongsheng@627: msgid "" dongsheng@627: "You will probably need to set the <envar>PYTHONPATH</envar> environment " dongsheng@627: "variable so that the Mercurial executable can find the rest of the Mercurial " dongsheng@627: "packages. For example, on my laptop, I have set it to <literal>/home/bos/lib/" dongsheng@627: "python</literal>. The exact path that you will need to use depends on how " dongsheng@627: "Python was built for your system, but should be easy to figure out. If " dongsheng@627: "you're uncertain, look through the output of the installer script above, and " dongsheng@627: "see where the contents of the <literal>mercurial</literal> directory were " dongsheng@627: "installed to." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appC-srcinstall.xml:44 dongsheng@627: msgid "On Windows" dongsheng@627: msgstr "Windows 系统" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:46 dongsheng@627: msgid "" dongsheng@627: "Building and installing Mercurial on Windows requires a variety of tools, a " dongsheng@627: "fair amount of technical knowledge, and considerable patience. I very much " dongsheng@627: "<emphasis>do not recommend</emphasis> this route if you are a <quote>casual " dongsheng@627: "user</quote>. Unless you intend to hack on Mercurial, I strongly suggest " dongsheng@627: "that you use a binary package instead." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appC-srcinstall.xml:53 dongsheng@627: msgid "" dongsheng@627: "If you are intent on building Mercurial from source on Windows, follow the " dongsheng@627: "<quote>hard way</quote> directions on the Mercurial wiki at <ulink url=" dongsheng@627: "\"http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall\">http://www." dongsheng@627: "selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>, and expect the " dongsheng@627: "process to involve a lot of fiddly work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><title> dongsheng@627: #: ../en/appD-license.xml:5 dongsheng@627: msgid "Open Publication License" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><para> dongsheng@627: #: ../en/appD-license.xml:7 dongsheng@627: msgid "Version 1.0, 8 June 1999" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:10 dongsheng@627: msgid "Requirements on both unmodified and modified versions" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:13 dongsheng@627: msgid "" dongsheng@627: "The Open Publication works may be reproduced and distributed in whole or in " dongsheng@627: "part, in any medium physical or electronic, provided that the terms of this " dongsheng@627: "license are adhered to, and that this license or an incorporation of it by " dongsheng@627: "reference (with any options elected by the author(s) and/or publisher) is " dongsheng@627: "displayed in the reproduction." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:20 dongsheng@627: msgid "Proper form for an incorporation by reference is as follows:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><blockquote><para> dongsheng@627: #: ../en/appD-license.xml:24 dongsheng@627: msgid "" dongsheng@627: "Copyright (c) <emphasis>year</emphasis> by <emphasis>author's name or " dongsheng@627: "designee</emphasis>. This material may be distributed only subject to the " dongsheng@627: "terms and conditions set forth in the Open Publication License, v<emphasis>x." dongsheng@627: "y</emphasis> or later (the latest version is presently available at <ulink " dongsheng@627: "url=\"http://www.opencontent.org/openpub/\">http://www.opencontent.org/" dongsheng@627: "openpub/</ulink>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:33 dongsheng@627: msgid "" dongsheng@627: "The reference must be immediately followed with any options elected by the " dongsheng@627: "author(s) and/or publisher of the document (see section <xref linkend=\"sec." dongsheng@627: "opl.options\"/>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:37 dongsheng@627: msgid "" dongsheng@627: "Commercial redistribution of Open Publication-licensed material is permitted." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:40 dongsheng@627: msgid "" dongsheng@627: "Any publication in standard (paper) book form shall require the citation of " dongsheng@627: "the original publisher and author. The publisher and author's names shall " dongsheng@627: "appear on all outer surfaces of the book. On all outer surfaces of the book " dongsheng@627: "the original publisher's name shall be as large as the title of the work and " dongsheng@627: "cited as possessive with respect to the title." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:49 dongsheng@627: msgid "Copyright" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:51 dongsheng@627: msgid "" dongsheng@627: "The copyright to each Open Publication is owned by its author(s) or designee." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:56 dongsheng@627: msgid "Scope of license" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:58 dongsheng@627: msgid "" dongsheng@627: "The following license terms apply to all Open Publication works, unless " dongsheng@627: "otherwise explicitly stated in the document." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:62 dongsheng@627: msgid "" dongsheng@627: "Mere aggregation of Open Publication works or a portion of an Open " dongsheng@627: "Publication work with other works or programs on the same media shall not " dongsheng@627: "cause this license to apply to those other works. The aggregate work shall " dongsheng@627: "contain a notice specifying the inclusion of the Open Publication material " dongsheng@627: "and appropriate copyright notice." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:69 dongsheng@627: msgid "" dongsheng@627: "<emphasis role=\"bold\">Severability</emphasis>. If any part of this license " dongsheng@627: "is found to be unenforceable in any jurisdiction, the remaining portions of " dongsheng@627: "the license remain in force." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:74 dongsheng@627: msgid "" dongsheng@627: "<emphasis role=\"bold\">No warranty</emphasis>. Open Publication works are " dongsheng@627: "licensed and provided <quote>as is</quote> without warranty of any kind, " dongsheng@627: "express or implied, including, but not limited to, the implied warranties of " dongsheng@627: "merchantability and fitness for a particular purpose or a warranty of non-" dongsheng@627: "infringement." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:83 dongsheng@627: msgid "Requirements on modified works" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:85 dongsheng@627: msgid "" dongsheng@627: "All modified versions of documents covered by this license, including " dongsheng@627: "translations, anthologies, compilations and partial documents, must meet the " dongsheng@627: "following requirements:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:90 dongsheng@627: msgid "The modified version must be labeled as such." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:93 dongsheng@627: msgid "" dongsheng@627: "The person making the modifications must be identified and the modifications " dongsheng@627: "dated." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:96 dongsheng@627: msgid "" dongsheng@627: "Acknowledgement of the original author and publisher if applicable must be " dongsheng@627: "retained according to normal academic citation practices." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:100 dongsheng@627: msgid "The location of the original unmodified document must be identified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:103 dongsheng@627: msgid "" dongsheng@627: "The original author's (or authors') name(s) may not be used to assert or " dongsheng@627: "imply endorsement of the resulting document without the original author's (or " dongsheng@627: "authors') permission." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:111 dongsheng@627: msgid "Good-practice recommendations" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:113 dongsheng@627: msgid "" dongsheng@627: "In addition to the requirements of this license, it is requested from and " dongsheng@627: "strongly recommended of redistributors that:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:118 dongsheng@627: msgid "" dongsheng@627: "If you are distributing Open Publication works on hardcopy or CD-ROM, you " dongsheng@627: "provide email notification to the authors of your intent to redistribute at " dongsheng@627: "least thirty days before your manuscript or media freeze, to give the authors " dongsheng@627: "time to provide updated documents. This notification should describe " dongsheng@627: "modifications, if any, made to the document." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:125 dongsheng@627: msgid "" dongsheng@627: "All substantive modifications (including deletions) be either clearly marked " dongsheng@627: "up in the document or else described in an attachment to the document." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:129 dongsheng@627: msgid "" dongsheng@627: "Finally, while it is not mandatory under this license, it is considered good " dongsheng@627: "form to offer a free copy of any hardcopy and CD-ROM expression of an Open " dongsheng@627: "Publication-licensed work to its author(s)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><title> dongsheng@627: #: ../en/appD-license.xml:137 dongsheng@627: msgid "License options" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><para> dongsheng@627: #: ../en/appD-license.xml:139 dongsheng@627: msgid "" dongsheng@627: "The author(s) and/or publisher of an Open Publication-licensed document may " dongsheng@627: "elect certain options by appending language to the reference to or copy of " dongsheng@627: "the license. These options are considered part of the license instance and " dongsheng@627: "must be included with the license (or its incorporation by reference) in " dongsheng@627: "derived works." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:147 dongsheng@627: msgid "" dongsheng@627: "To prohibit distribution of substantively modified versions without the " dongsheng@627: "explicit permission of the author(s). <quote>Substantive modification</quote> " dongsheng@627: "is defined as a change to the semantic content of the document, and excludes " dongsheng@627: "mere changes in format or typographical corrections." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:154 dongsheng@627: msgid "" dongsheng@627: "To accomplish this, add the phrase <quote>Distribution of substantively " dongsheng@627: "modified versions of this document is prohibited without the explicit " dongsheng@627: "permission of the copyright holder.</quote> to the license reference or copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:160 dongsheng@627: msgid "" dongsheng@627: "To prohibit any publication of this work or derivative works in whole or in " dongsheng@627: "part in standard (paper) book form for commercial purposes is prohibited " dongsheng@627: "unless prior permission is obtained from the copyright holder." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><appendix><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/appD-license.xml:165 dongsheng@627: msgid "" dongsheng@627: "To accomplish this, add the phrase <quote>Distribution of the work or " dongsheng@627: "derivative of the work in any standard (paper) book form is prohibited unless " dongsheng@627: "prior permission is obtained from the copyright holder.</quote> to the " dongsheng@627: "license reference or copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch01-intro.xml:5 dongsheng@627: msgid "Introduction" dongsheng@627: msgstr "简介" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:8 dongsheng@627: msgid "About revision control" dongsheng@627: msgstr "关于版本控制" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:10 dongsheng@627: msgid "" dongsheng@627: "Revision control is the process of managing multiple versions of a piece of " dongsheng@627: "information. In its simplest form, this is something that many people do by " dongsheng@627: "hand: every time you modify a file, save it under a new name that contains a " dongsheng@627: "number, each one higher than the number of the preceding version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:16 dongsheng@627: msgid "" dongsheng@627: "Manually managing multiple versions of even a single file is an error-prone " dongsheng@627: "task, though, so software tools to help automate this process have long been " dongsheng@627: "available. The earliest automated revision control tools were intended to " dongsheng@627: "help a single user to manage revisions of a single file. Over the past few " dongsheng@627: "decades, the scope of revision control tools has expanded greatly; they now " dongsheng@627: "manage multiple files, and help multiple people to work together. The best " dongsheng@627: "modern revision control tools have no problem coping with thousands of people " dongsheng@627: "working together on projects that consist of hundreds of thousands of files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:28 dongsheng@627: msgid "Why use revision control?" dongsheng@627: msgstr "为什么使用版本控制?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:30 dongsheng@627: msgid "" dongsheng@627: "There are a number of reasons why you or your team might want to use an " dongsheng@627: "automated revision control tool for a project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:34 dongsheng@627: msgid "" dongsheng@627: "It will track the history and evolution of your project, so you don't have " dongsheng@627: "to. For every change, you'll have a log of <emphasis>who</emphasis> made it; " dongsheng@627: "<emphasis>why</emphasis> they made it; <emphasis>when</emphasis> they made " dongsheng@627: "it; and <emphasis>what</emphasis> the change was." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:41 dongsheng@627: msgid "" dongsheng@627: "When you're working with other people, revision control software makes it " dongsheng@627: "easier for you to collaborate. For example, when people more or less " dongsheng@627: "simultaneously make potentially incompatible changes, the software will help " dongsheng@627: "you to identify and resolve those conflicts." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:47 dongsheng@627: msgid "" dongsheng@627: "It can help you to recover from mistakes. If you make a change that later " dongsheng@627: "turns out to be in error, you can revert to an earlier version of one or more " dongsheng@627: "files. In fact, a <emphasis>really</emphasis> good revision control tool " dongsheng@627: "will even help you to efficiently figure out exactly when a problem was " dongsheng@627: "introduced (see section <xref linkend=\"sec.undo.bisect\"/> for details)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:54 dongsheng@627: msgid "" dongsheng@627: "It will help you to work simultaneously on, and manage the drift between, " dongsheng@627: "multiple versions of your project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:57 dongsheng@627: msgid "" dongsheng@627: "Most of these reasons are equally valid---at least in theory---whether you're " dongsheng@627: "working on a project by yourself, or with a hundred other people." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:61 dongsheng@627: msgid "" dongsheng@627: "A key question about the practicality of revision control at these two " dongsheng@627: "different scales (<quote>lone hacker</quote> and <quote>huge team</quote>) is " dongsheng@627: "how its <emphasis>benefits</emphasis> compare to its <emphasis>costs</" dongsheng@627: "emphasis>. A revision control tool that's difficult to understand or use is " dongsheng@627: "going to impose a high cost." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:69 dongsheng@627: msgid "" dongsheng@627: "A five-hundred-person project is likely to collapse under its own weight " dongsheng@627: "almost immediately without a revision control tool and process. In this case, " dongsheng@627: "the cost of using revision control might hardly seem worth considering, since " dongsheng@627: "<emphasis>without</emphasis> it, failure is almost guaranteed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:76 dongsheng@627: msgid "" dongsheng@627: "On the other hand, a one-person <quote>quick hack</quote> might seem like a " dongsheng@627: "poor place to use a revision control tool, because surely the cost of using " dongsheng@627: "one must be close to the overall cost of the project. Right?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:81 dongsheng@627: msgid "" dongsheng@627: "Mercurial uniquely supports <emphasis>both</emphasis> of these scales of " dongsheng@627: "development. You can learn the basics in just a few minutes, and due to its " dongsheng@627: "low overhead, you can apply revision control to the smallest of projects with " dongsheng@627: "ease. Its simplicity means you won't have a lot of abstruse concepts or " dongsheng@627: "command sequences competing for mental space with whatever you're " dongsheng@627: "<emphasis>really</emphasis> trying to do. At the same time, Mercurial's high " dongsheng@627: "performance and peer-to-peer nature let you scale painlessly to handle large " dongsheng@627: "projects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:91 dongsheng@627: msgid "" dongsheng@627: "No revision control tool can rescue a poorly run project, but a good choice " dongsheng@627: "of tools can make a huge difference to the fluidity with which you can work " dongsheng@627: "on a project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:97 dongsheng@627: msgid "The many names of revision control" dongsheng@627: msgstr "版本控制的别名" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:99 dongsheng@627: msgid "" dongsheng@627: "Revision control is a diverse field, so much so that it doesn't actually have " dongsheng@627: "a single name or acronym. Here are a few of the more common names and " dongsheng@627: "acronyms you'll encounter:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:104 dongsheng@627: msgid "Revision control (RCS)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:105 dongsheng@627: msgid "Software configuration management (SCM), or configuration management" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:107 dongsheng@627: msgid "Source code management" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:108 dongsheng@627: msgid "Source code control, or source control" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:110 dongsheng@627: msgid "Version control (VCS)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:112 dongsheng@627: msgid "" dongsheng@627: "Some people claim that these terms actually have different meanings, but in " dongsheng@627: "practice they overlap so much that there's no agreed or even useful way to " dongsheng@627: "tease them apart." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:119 dongsheng@627: msgid "A short history of revision control" dongsheng@627: msgstr "版本控制简史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:121 dongsheng@627: msgid "" dongsheng@627: "The best known of the old-time revision control tools is SCCS (Source Code " dongsheng@627: "Control System), which Marc Rochkind wrote at Bell Labs, in the early 1970s. " dongsheng@627: "SCCS operated on individual files, and required every person working on a " dongsheng@627: "project to have access to a shared workspace on a single system. Only one " dongsheng@627: "person could modify a file at any time; arbitration for access to files was " dongsheng@627: "via locks. It was common for people to lock files, and later forget to " dongsheng@627: "unlock them, preventing anyone else from modifying those files without the " dongsheng@627: "help of an administrator." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:132 dongsheng@627: msgid "" dongsheng@627: "Walter Tichy developed a free alternative to SCCS in the early 1980s; he " dongsheng@627: "called his program RCS (Revision Control System). Like SCCS, RCS required " dongsheng@627: "developers to work in a single shared workspace, and to lock files to prevent " dongsheng@627: "multiple people from modifying them simultaneously." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:138 dongsheng@627: msgid "" dongsheng@627: "Later in the 1980s, Dick Grune used RCS as a building block for a set of " dongsheng@627: "shell scripts he initially called cmt, but then renamed to CVS (Concurrent " dongsheng@627: "Versions System). The big innovation of CVS was that it let developers work " dongsheng@627: "simultaneously and somewhat independently in their own personal workspaces. " dongsheng@627: "The personal workspaces prevented developers from stepping on each other's " dongsheng@627: "toes all the time, as was common with SCCS and RCS. Each developer had a copy " dongsheng@627: "of every project file, and could modify their copies independently. They had " dongsheng@627: "to merge their edits prior to committing changes to the central repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:149 dongsheng@627: msgid "" dongsheng@627: "Brian Berliner took Grune's original scripts and rewrote them in C, releasing " dongsheng@627: "in 1989 the code that has since developed into the modern version of CVS. " dongsheng@627: "CVS subsequently acquired the ability to operate over a network connection, " dongsheng@627: "giving it a client/server architecture. CVS's architecture is centralised; " dongsheng@627: "only the server has a copy of the history of the project. Client workspaces " dongsheng@627: "just contain copies of recent versions of the project's files, and a little " dongsheng@627: "metadata to tell them where the server is. CVS has been enormously " dongsheng@627: "successful; it is probably the world's most widely used revision control " dongsheng@627: "system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:160 dongsheng@627: msgid "" dongsheng@627: "In the early 1990s, Sun Microsystems developed an early distributed revision " dongsheng@627: "control system, called TeamWare. A TeamWare workspace contains a complete " dongsheng@627: "copy of the project's history. TeamWare has no notion of a central " dongsheng@627: "repository. (CVS relied upon RCS for its history storage; TeamWare used " dongsheng@627: "SCCS.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:167 dongsheng@627: msgid "" dongsheng@627: "As the 1990s progressed, awareness grew of a number of problems with CVS. It " dongsheng@627: "records simultaneous changes to multiple files individually, instead of " dongsheng@627: "grouping them together as a single logically atomic operation. It does not " dongsheng@627: "manage its file hierarchy well; it is easy to make a mess of a repository by " dongsheng@627: "renaming files and directories. Worse, its source code is difficult to read " dongsheng@627: "and maintain, which made the <quote>pain level</quote> of fixing these " dongsheng@627: "architectural problems prohibitive." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:177 dongsheng@627: msgid "" dongsheng@627: "In 2001, Jim Blandy and Karl Fogel, two developers who had worked on CVS, " dongsheng@627: "started a project to replace it with a tool that would have a better " dongsheng@627: "architecture and cleaner code. The result, Subversion, does not stray from " dongsheng@627: "CVS's centralised client/server model, but it adds multi-file atomic commits, " dongsheng@627: "better namespace management, and a number of other features that make it a " dongsheng@627: "generally better tool than CVS. Since its initial release, it has rapidly " dongsheng@627: "grown in popularity." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:186 dongsheng@627: msgid "" dongsheng@627: "More or less simultaneously, Graydon Hoare began working on an ambitious " dongsheng@627: "distributed revision control system that he named Monotone. While Monotone " dongsheng@627: "addresses many of CVS's design flaws and has a peer-to-peer architecture, it " dongsheng@627: "goes beyond earlier (and subsequent) revision control tools in a number of " dongsheng@627: "innovative ways. It uses cryptographic hashes as identifiers, and has an " dongsheng@627: "integral notion of <quote>trust</quote> for code from different sources." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:195 dongsheng@627: msgid "" dongsheng@627: "Mercurial began life in 2005. While a few aspects of its design are " dongsheng@627: "influenced by Monotone, Mercurial focuses on ease of use, high performance, " dongsheng@627: "and scalability to very large projects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:202 dongsheng@627: msgid "Trends in revision control" dongsheng@627: msgstr "版本控制的发展趋势" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:204 dongsheng@627: msgid "" dongsheng@627: "There has been an unmistakable trend in the development and use of revision " dongsheng@627: "control tools over the past four decades, as people have become familiar with " dongsheng@627: "the capabilities of their tools and constrained by their limitations." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:209 dongsheng@627: msgid "" dongsheng@627: "The first generation began by managing single files on individual computers. " dongsheng@627: "Although these tools represented a huge advance over ad-hoc manual revision " dongsheng@627: "control, their locking model and reliance on a single computer limited them " dongsheng@627: "to small, tightly-knit teams." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:215 dongsheng@627: msgid "" dongsheng@627: "The second generation loosened these constraints by moving to network-" dongsheng@627: "centered architectures, and managing entire projects at a time. As projects " dongsheng@627: "grew larger, they ran into new problems. With clients needing to talk to " dongsheng@627: "servers very frequently, server scaling became an issue for large projects. " dongsheng@627: "An unreliable network connection could prevent remote users from being able " dongsheng@627: "to talk to the server at all. As open source projects started making read-" dongsheng@627: "only access available anonymously to anyone, people without commit privileges " dongsheng@627: "found that they could not use the tools to interact with a project in a " dongsheng@627: "natural way, as they could not record their changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:227 dongsheng@627: msgid "" dongsheng@627: "The current generation of revision control tools is peer-to-peer in nature. " dongsheng@627: "All of these systems have dropped the dependency on a single central server, " dongsheng@627: "and allow people to distribute their revision control data to where it's " dongsheng@627: "actually needed. Collaboration over the Internet has moved from constrained " dongsheng@627: "by technology to a matter of choice and consensus. Modern tools can operate " dongsheng@627: "offline indefinitely and autonomously, with a network connection only needed " dongsheng@627: "when syncing changes with another repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:239 dongsheng@627: msgid "A few of the advantages of distributed revision control" dongsheng@627: msgstr "分布版本控制的优点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:242 dongsheng@627: msgid "" dongsheng@627: "Even though distributed revision control tools have for several years been as " dongsheng@627: "robust and usable as their previous-generation counterparts, people using " dongsheng@627: "older tools have not yet necessarily woken up to their advantages. There are " dongsheng@627: "a number of ways in which distributed tools shine relative to centralised " dongsheng@627: "ones." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:249 dongsheng@627: msgid "" dongsheng@627: "For an individual developer, distributed tools are almost always much faster " dongsheng@627: "than centralised tools. This is for a simple reason: a centralised tool " dongsheng@627: "needs to talk over the network for many common operations, because most " dongsheng@627: "metadata is stored in a single copy on the central server. A distributed " dongsheng@627: "tool stores all of its metadata locally. All else being equal, talking over " dongsheng@627: "the network adds overhead to a centralised tool. Don't underestimate the " dongsheng@627: "value of a snappy, responsive tool: you're going to spend a lot of time " dongsheng@627: "interacting with your revision control software." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:260 dongsheng@627: msgid "" dongsheng@627: "Distributed tools are indifferent to the vagaries of your server " dongsheng@627: "infrastructure, again because they replicate metadata to so many locations. " dongsheng@627: "If you use a centralised system and your server catches fire, you'd better " dongsheng@627: "hope that your backup media are reliable, and that your last backup was " dongsheng@627: "recent and actually worked. With a distributed tool, you have many backups " dongsheng@627: "available on every contributor's computer." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:268 dongsheng@627: msgid "" dongsheng@627: "The reliability of your network will affect distributed tools far less than " dongsheng@627: "it will centralised tools. You can't even use a centralised tool without a " dongsheng@627: "network connection, except for a few highly constrained commands. With a " dongsheng@627: "distributed tool, if your network connection goes down while you're working, " dongsheng@627: "you may not even notice. The only thing you won't be able to do is talk to " dongsheng@627: "repositories on other computers, something that is relatively rare compared " dongsheng@627: "with local operations. If you have a far-flung team of collaborators, this " dongsheng@627: "may be significant." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:279 dongsheng@627: msgid "Advantages for open source projects" dongsheng@627: msgstr "开源项目的优点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:281 dongsheng@627: msgid "" dongsheng@627: "If you take a shine to an open source project and decide that you would like " dongsheng@627: "to start hacking on it, and that project uses a distributed revision control " dongsheng@627: "tool, you are at once a peer with the people who consider themselves the " dongsheng@627: "<quote>core</quote> of that project. If they publish their repositories, you " dongsheng@627: "can immediately copy their project history, start making changes, and record " dongsheng@627: "your work, using the same tools in the same ways as insiders. By contrast, " dongsheng@627: "with a centralised tool, you must use the software in a <quote>read only</" dongsheng@627: "quote> mode unless someone grants you permission to commit changes to their " dongsheng@627: "central server. Until then, you won't be able to record changes, and your " dongsheng@627: "local modifications will be at risk of corruption any time you try to update " dongsheng@627: "your client's view of the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch01-intro.xml:297 dongsheng@627: msgid "The forking non-problem" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:299 dongsheng@627: msgid "" dongsheng@627: "It has been suggested that distributed revision control tools pose some sort " dongsheng@627: "of risk to open source projects because they make it easy to <quote>fork</" dongsheng@627: "quote> the development of a project. A fork happens when there are " dongsheng@627: "differences in opinion or attitude between groups of developers that cause " dongsheng@627: "them to decide that they can't work together any longer. Each side takes a " dongsheng@627: "more or less complete copy of the project's source code, and goes off in its " dongsheng@627: "own direction." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:309 dongsheng@627: msgid "" dongsheng@627: "Sometimes the camps in a fork decide to reconcile their differences. With a " dongsheng@627: "centralised revision control system, the <emphasis>technical</emphasis> " dongsheng@627: "process of reconciliation is painful, and has to be performed largely by " dongsheng@627: "hand. You have to decide whose revision history is going to <quote>win</" dongsheng@627: "quote>, and graft the other team's changes into the tree somehow. This " dongsheng@627: "usually loses some or all of one side's revision history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:318 dongsheng@627: msgid "" dongsheng@627: "What distributed tools do with respect to forking is they make forking the " dongsheng@627: "<emphasis>only</emphasis> way to develop a project. Every single change that " dongsheng@627: "you make is potentially a fork point. The great strength of this approach is " dongsheng@627: "that a distributed revision control tool has to be really good at " dongsheng@627: "<emphasis>merging</emphasis> forks, because forks are absolutely fundamental: " dongsheng@627: "they happen all the time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:327 dongsheng@627: msgid "" dongsheng@627: "If every piece of work that everybody does, all the time, is framed in terms " dongsheng@627: "of forking and merging, then what the open source world refers to as a " dongsheng@627: "<quote>fork</quote> becomes <emphasis>purely</emphasis> a social issue. If " dongsheng@627: "anything, distributed tools <emphasis>lower</emphasis> the likelihood of a " dongsheng@627: "fork:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:334 dongsheng@627: msgid "" dongsheng@627: "They eliminate the social distinction that centralised tools impose: that " dongsheng@627: "between insiders (people with commit access) and outsiders (people without)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:338 dongsheng@627: msgid "" dongsheng@627: "They make it easier to reconcile after a social fork, because all that's " dongsheng@627: "involved from the perspective of the revision control software is just " dongsheng@627: "another merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch01-intro.xml:343 dongsheng@627: msgid "" dongsheng@627: "Some people resist distributed tools because they want to retain tight " dongsheng@627: "control over their projects, and they believe that centralised tools give " dongsheng@627: "them this control. However, if you're of this belief, and you publish your " dongsheng@627: "CVS or Subversion repositories publicly, there are plenty of tools available " dongsheng@627: "that can pull out your entire project's history (albeit slowly) and recreate " dongsheng@627: "it somewhere that you don't control. So while your control in this case is " dongsheng@627: "illusory, you are forgoing the ability to fluidly collaborate with whatever " dongsheng@627: "people feel compelled to mirror and fork your history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:358 dongsheng@627: msgid "Advantages for commercial projects" dongsheng@627: msgstr "商业项目的优点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:360 dongsheng@627: msgid "" dongsheng@627: "Many commercial projects are undertaken by teams that are scattered across " dongsheng@627: "the globe. Contributors who are far from a central server will see slower " dongsheng@627: "command execution and perhaps less reliability. Commercial revision control " dongsheng@627: "systems attempt to ameliorate these problems with remote-site replication add-" dongsheng@627: "ons that are typically expensive to buy and cantankerous to administer. A " dongsheng@627: "distributed system doesn't suffer from these problems in the first place. " dongsheng@627: "Better yet, you can easily set up multiple authoritative servers, say one per " dongsheng@627: "site, so that there's no redundant communication between repositories over " dongsheng@627: "expensive long-haul network links." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:372 dongsheng@627: msgid "" dongsheng@627: "Centralised revision control systems tend to have relatively low " dongsheng@627: "scalability. It's not unusual for an expensive centralised system to fall " dongsheng@627: "over under the combined load of just a few dozen concurrent users. Once " dongsheng@627: "again, the typical response tends to be an expensive and clunky replication " dongsheng@627: "facility. Since the load on a central server---if you have one at all---is " dongsheng@627: "many times lower with a distributed tool (because all of the data is " dongsheng@627: "replicated everywhere), a single cheap server can handle the needs of a much " dongsheng@627: "larger team, and replication to balance load becomes a simple matter of " dongsheng@627: "scripting." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:384 dongsheng@627: msgid "" dongsheng@627: "If you have an employee in the field, troubleshooting a problem at a " dongsheng@627: "customer's site, they'll benefit from distributed revision control. The tool " dongsheng@627: "will let them generate custom builds, try different fixes in isolation from " dongsheng@627: "each other, and search efficiently through history for the sources of bugs " dongsheng@627: "and regressions in the customer's environment, all without needing to connect " dongsheng@627: "to your company's network." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:395 dongsheng@627: msgid "Why choose Mercurial?" dongsheng@627: msgstr "为什么选择 Mercurial?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:397 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a unique set of properties that make it a particularly good " dongsheng@627: "choice as a revision control system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:400 dongsheng@627: msgid "It is easy to learn and use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:401 dongsheng@627: msgid "It is lightweight." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:402 dongsheng@627: msgid "It scales excellently." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:403 dongsheng@627: msgid "It is easy to customise." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:406 dongsheng@627: msgid "" dongsheng@627: "If you are at all familiar with revision control systems, you should be able " dongsheng@627: "to get up and running with Mercurial in less than five minutes. Even if not, " dongsheng@627: "it will take no more than a few minutes longer. Mercurial's command and " dongsheng@627: "feature sets are generally uniform and consistent, so you can keep track of a " dongsheng@627: "few general rules instead of a host of exceptions." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:413 dongsheng@627: msgid "" dongsheng@627: "On a small project, you can start working with Mercurial in moments. Creating " dongsheng@627: "new changes and branches; transferring changes around (whether locally or " dongsheng@627: "over a network); and history and status operations are all fast. Mercurial " dongsheng@627: "attempts to stay nimble and largely out of your way by combining low " dongsheng@627: "cognitive overhead with blazingly fast operations." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:420 dongsheng@627: msgid "" dongsheng@627: "The usefulness of Mercurial is not limited to small projects: it is used by " dongsheng@627: "projects with hundreds to thousands of contributors, each containing tens of " dongsheng@627: "thousands of files and hundreds of megabytes of source code." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:425 dongsheng@627: msgid "" dongsheng@627: "If the core functionality of Mercurial is not enough for you, it's easy to " dongsheng@627: "build on. Mercurial is well suited to scripting tasks, and its clean " dongsheng@627: "internals and implementation in Python make it easy to add features in the " dongsheng@627: "form of extensions. There are a number of popular and useful extensions " dongsheng@627: "already available, ranging from helping to identify bugs to improving " dongsheng@627: "performance." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:435 dongsheng@627: msgid "Mercurial compared with other tools" dongsheng@627: msgstr "Mercurial 与其它工具的比较" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:437 dongsheng@627: msgid "" dongsheng@627: "Before you read on, please understand that this section necessarily reflects " dongsheng@627: "my own experiences, interests, and (dare I say it) biases. I have used every " dongsheng@627: "one of the revision control tools listed below, in most cases for several " dongsheng@627: "years at a time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:445 ../en/ch01-intro.xml:656 dongsheng@627: msgid "Subversion" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:447 dongsheng@627: msgid "" dongsheng@627: "Subversion is a popular revision control tool, developed to replace CVS. It " dongsheng@627: "has a centralised client/server architecture." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:451 dongsheng@627: msgid "" dongsheng@627: "Subversion and Mercurial have similarly named commands for performing the " dongsheng@627: "same operations, so if you're familiar with one, it is easy to learn to use " dongsheng@627: "the other. Both tools are portable to all popular operating systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:456 dongsheng@627: msgid "" dongsheng@627: "Prior to version 1.5, Subversion had no useful support for merges. At the " dongsheng@627: "time of writing, its merge tracking capability is new, and known to be <ulink " dongsheng@627: "url=\"http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced." dongsheng@627: "html#svn.branchmerge.advanced.finalword\">complicated and buggy</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:462 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a substantial performance advantage over Subversion on every " dongsheng@627: "revision control operation I have benchmarked. I have measured its advantage " dongsheng@627: "as ranging from a factor of two to a factor of six when compared with " dongsheng@627: "Subversion 1.4.3's <emphasis>ra_local</emphasis> file store, which is the " dongsheng@627: "fastest access method available. In more realistic deployments involving a " dongsheng@627: "network-based store, Subversion will be at a substantially larger " dongsheng@627: "disadvantage. Because many Subversion commands must talk to the server and " dongsheng@627: "Subversion does not have useful replication facilities, server capacity and " dongsheng@627: "network bandwidth become bottlenecks for modestly large projects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:475 dongsheng@627: msgid "" dongsheng@627: "Additionally, Subversion incurs substantial storage overhead to avoid network " dongsheng@627: "transactions for a few common operations, such as finding modified files " dongsheng@627: "(<literal>status</literal>) and displaying modifications against the current " dongsheng@627: "revision (<literal>diff</literal>). As a result, a Subversion working copy " dongsheng@627: "is often the same size as, or larger than, a Mercurial repository and working " dongsheng@627: "directory, even though the Mercurial repository contains a complete history " dongsheng@627: "of the project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:485 dongsheng@627: msgid "" dongsheng@627: "Subversion is widely supported by third party tools. Mercurial currently " dongsheng@627: "lags considerably in this area. This gap is closing, however, and indeed " dongsheng@627: "some of Mercurial's GUI tools now outshine their Subversion equivalents. " dongsheng@627: "Like Mercurial, Subversion has an excellent user manual." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:491 dongsheng@627: msgid "" dongsheng@627: "Because Subversion doesn't store revision history on the client, it is well " dongsheng@627: "suited to managing projects that deal with lots of large, opaque binary " dongsheng@627: "files. If you check in fifty revisions to an incompressible 10MB file, " dongsheng@627: "Subversion's client-side space usage stays constant The space used by any " dongsheng@627: "distributed SCM will grow rapidly in proportion to the number of revisions, " dongsheng@627: "because the differences between each revision are large." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:500 dongsheng@627: msgid "" dongsheng@627: "In addition, it's often difficult or, more usually, impossible to merge " dongsheng@627: "different versions of a binary file. Subversion's ability to let a user lock " dongsheng@627: "a file, so that they temporarily have the exclusive right to commit changes " dongsheng@627: "to it, can be a significant advantage to a project where binary files are " dongsheng@627: "widely used." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:507 dongsheng@627: msgid "" dongsheng@627: "Mercurial can import revision history from a Subversion repository. It can " dongsheng@627: "also export revision history to a Subversion repository. This makes it easy " dongsheng@627: "to <quote>test the waters</quote> and use Mercurial and Subversion in " dongsheng@627: "parallel before deciding to switch. History conversion is incremental, so " dongsheng@627: "you can perform an initial conversion, then small additional conversions " dongsheng@627: "afterwards to bring in new changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:519 ../en/ch01-intro.xml:658 dongsheng@627: msgid "Git" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:521 dongsheng@627: msgid "" dongsheng@627: "Git is a distributed revision control tool that was developed for managing " dongsheng@627: "the Linux kernel source tree. Like Mercurial, its early design was somewhat " dongsheng@627: "influenced by Monotone." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:526 dongsheng@627: msgid "" dongsheng@627: "Git has a very large command set, with version 1.5.0 providing 139 individual " dongsheng@627: "commands. It has something of a reputation for being difficult to learn. " dongsheng@627: "Compared to Git, Mercurial has a strong focus on simplicity." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:531 dongsheng@627: msgid "" dongsheng@627: "In terms of performance, Git is extremely fast. In several cases, it is " dongsheng@627: "faster than Mercurial, at least on Linux, while Mercurial performs better on " dongsheng@627: "other operations. However, on Windows, the performance and general level of " dongsheng@627: "support that Git provides is, at the time of writing, far behind that of " dongsheng@627: "Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:538 dongsheng@627: msgid "" dongsheng@627: "While a Mercurial repository needs no maintenance, a Git repository requires " dongsheng@627: "frequent manual <quote>repacks</quote> of its metadata. Without these, " dongsheng@627: "performance degrades, while space usage grows rapidly. A server that " dongsheng@627: "contains many Git repositories that are not rigorously and frequently " dongsheng@627: "repacked will become heavily disk-bound during backups, and there have been " dongsheng@627: "instances of daily backups taking far longer than 24 hours as a result. A " dongsheng@627: "freshly packed Git repository is slightly smaller than a Mercurial " dongsheng@627: "repository, but an unpacked repository is several orders of magnitude larger." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:549 dongsheng@627: msgid "" dongsheng@627: "The core of Git is written in C. Many Git commands are implemented as shell " dongsheng@627: "or Perl scripts, and the quality of these scripts varies widely. I have " dongsheng@627: "encountered several instances where scripts charged along blindly in the " dongsheng@627: "presence of errors that should have been fatal." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:555 dongsheng@627: msgid "Mercurial can import revision history from a Git repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:561 ../en/ch01-intro.xml:657 dongsheng@627: msgid "CVS" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:563 dongsheng@627: msgid "" dongsheng@627: "CVS is probably the most widely used revision control tool in the world. Due " dongsheng@627: "to its age and internal untidiness, it has been only lightly maintained for " dongsheng@627: "many years." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:567 dongsheng@627: msgid "" dongsheng@627: "It has a centralised client/server architecture. It does not group related " dongsheng@627: "file changes into atomic commits, making it easy for people to <quote>break " dongsheng@627: "the build</quote>: one person can successfully commit part of a change and " dongsheng@627: "then be blocked by the need for a merge, causing other people to see only a " dongsheng@627: "portion of the work they intended to do. This also affects how you work with " dongsheng@627: "project history. If you want to see all of the modifications someone made as " dongsheng@627: "part of a task, you will need to manually inspect the descriptions and " dongsheng@627: "timestamps of the changes made to each file involved (if you even know what " dongsheng@627: "those files were)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:579 dongsheng@627: msgid "" dongsheng@627: "CVS has a muddled notion of tags and branches that I will not attempt to even " dongsheng@627: "describe. It does not support renaming of files or directories well, making " dongsheng@627: "it easy to corrupt a repository. It has almost no internal consistency " dongsheng@627: "checking capabilities, so it is usually not even possible to tell whether or " dongsheng@627: "how a repository is corrupt. I would not recommend CVS for any project, " dongsheng@627: "existing or new." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:587 dongsheng@627: msgid "" dongsheng@627: "Mercurial can import CVS revision history. However, there are a few caveats " dongsheng@627: "that apply; these are true of every other revision control tool's CVS " dongsheng@627: "importer, too. Due to CVS's lack of atomic changes and unversioned " dongsheng@627: "filesystem hierarchy, it is not possible to reconstruct CVS history " dongsheng@627: "completely accurately; some guesswork is involved, and renames will usually " dongsheng@627: "not show up. Because a lot of advanced CVS administration has to be done by " dongsheng@627: "hand and is hence error-prone, it's common for CVS importers to run into " dongsheng@627: "multiple problems with corrupted repositories (completely bogus revision " dongsheng@627: "timestamps and files that have remained locked for over a decade are just two " dongsheng@627: "of the less interesting problems I can recall from personal experience)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:601 dongsheng@627: msgid "Mercurial can import revision history from a CVS repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:607 dongsheng@627: msgid "Commercial tools" dongsheng@627: msgstr "商业工具" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:609 dongsheng@627: msgid "" dongsheng@627: "Perforce has a centralised client/server architecture, with no client-side " dongsheng@627: "caching of any data. Unlike modern revision control tools, Perforce requires " dongsheng@627: "that a user run a command to inform the server about every file they intend " dongsheng@627: "to edit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:615 dongsheng@627: msgid "" dongsheng@627: "The performance of Perforce is quite good for small teams, but it falls off " dongsheng@627: "rapidly as the number of users grows beyond a few dozen. Modestly large " dongsheng@627: "Perforce installations require the deployment of proxies to cope with the " dongsheng@627: "load their users generate." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch01-intro.xml:624 dongsheng@627: msgid "Choosing a revision control tool" dongsheng@627: msgstr "选择版本控制工具" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:626 dongsheng@627: msgid "" dongsheng@627: "With the exception of CVS, all of the tools listed above have unique " dongsheng@627: "strengths that suit them to particular styles of work. There is no single " dongsheng@627: "revision control tool that is best in all situations." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:631 dongsheng@627: msgid "" dongsheng@627: "As an example, Subversion is a good choice for working with frequently edited " dongsheng@627: "binary files, due to its centralised nature and support for file locking." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch01-intro.xml:635 dongsheng@627: msgid "" dongsheng@627: "I personally find Mercurial's properties of simplicity, performance, and good " dongsheng@627: "merge support to be a compelling combination that has served me well for " dongsheng@627: "several years." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch01-intro.xml:643 dongsheng@627: msgid "Switching from another tool to Mercurial" dongsheng@627: msgstr "从其它工具切换到 Mercurial" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:645 dongsheng@627: msgid "" dongsheng@627: "Mercurial is bundled with an extension named <literal role=\"hg-ext" dongsheng@627: "\">convert</literal>, which can incrementally import revision history from " dongsheng@627: "several other revision control tools. By <quote>incremental</quote>, I mean " dongsheng@627: "that you can convert all of a project's history to date in one go, then rerun " dongsheng@627: "the conversion later to obtain new changes that happened after the initial " dongsheng@627: "conversion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:653 dongsheng@627: msgid "" dongsheng@627: "The revision control tools supported by <literal role=\"hg-ext\">convert</" dongsheng@627: "literal> are as follows:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch01-intro.xml:659 dongsheng@627: msgid "Darcs" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:661 dongsheng@627: msgid "" dongsheng@627: "In addition, <literal role=\"hg-ext\">convert</literal> can export changes " dongsheng@627: "from Mercurial to Subversion. This makes it possible to try Subversion and " dongsheng@627: "Mercurial in parallel before committing to a switchover, without risking the " dongsheng@627: "loss of any work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch01-intro.xml:667 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-conver\">convert</command> command is easy to " dongsheng@627: "use. Simply point it at the path or URL of the source repository, optionally " dongsheng@627: "give it the name of the destination repository, and it will start working. " dongsheng@627: "After the initial conversion, just run the same command again to import new " dongsheng@627: "changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:5 dongsheng@627: msgid "A tour of Mercurial: the basics" dongsheng@627: msgstr "Mercurial 教程: 基础知识" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:8 dongsheng@627: msgid "Installing Mercurial on your system" dongsheng@627: msgstr "安装 Mercurial" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:10 dongsheng@627: msgid "" dongsheng@627: "Prebuilt binary packages of Mercurial are available for every popular " dongsheng@627: "operating system. These make it easy to start using Mercurial on your " dongsheng@627: "computer immediately." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:15 dongsheng@627: msgid "Linux" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:17 dongsheng@627: msgid "" dongsheng@627: "Because each Linux distribution has its own packaging tools, policies, and " dongsheng@627: "rate of development, it's difficult to give a comprehensive set of " dongsheng@627: "instructions on how to install Mercurial binaries. The version of Mercurial " dongsheng@627: "that you will end up with can vary depending on how active the person is who " dongsheng@627: "maintains the package for your distribution." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:24 dongsheng@627: msgid "" dongsheng@627: "To keep things simple, I will focus on installing Mercurial from the command " dongsheng@627: "line under the most popular Linux distributions. Most of these distributions " dongsheng@627: "provide graphical package managers that will let you install Mercurial with a " dongsheng@627: "single click; the package name to look for is <literal>mercurial</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:32 dongsheng@627: msgid "Debian:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:35 dongsheng@627: msgid "Fedora Core:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:38 dongsheng@627: msgid "Gentoo:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:40 dongsheng@627: msgid "OpenSUSE:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:43 dongsheng@627: msgid "" dongsheng@627: "Ubuntu: Ubuntu's Mercurial package is based on Debian's. To install it, run " dongsheng@627: "the following command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:52 dongsheng@627: msgid "Solaris" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:54 dongsheng@627: msgid "" dongsheng@627: "SunFreeWare, at <ulink url=\"http://www.sunfreeware.com\">http://www." dongsheng@627: "sunfreeware.com</ulink>, is a good source for a large number of pre-built " dongsheng@627: "Solaris packages for 32 and 64 bit Intel and Sparc architectures, including " dongsheng@627: "current versions of Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:62 dongsheng@627: msgid "Mac OS X" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:64 dongsheng@627: msgid "" dongsheng@627: "Lee Cantey publishes an installer of Mercurial for Mac OS X at <ulink url=" dongsheng@627: "\"http://mercurial.berkwood.com\">http://mercurial.berkwood.com</ulink>. " dongsheng@627: "This package works on both Intel- and Power-based Macs. Before you can use " dongsheng@627: "it, you must install a compatible version of Universal MacPython " dongsheng@627: "<citation>web:macpython</citation>. This is easy to do; simply follow the " dongsheng@627: "instructions on Lee's site." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:73 dongsheng@627: msgid "" dongsheng@627: "It's also possible to install Mercurial using Fink or MacPorts, two popular " dongsheng@627: "free package managers for Mac OS X. If you have Fink, use <command>sudo apt-" dongsheng@627: "get install mercurial-py25</command>. If MacPorts, <command>sudo port " dongsheng@627: "install mercurial</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:81 dongsheng@627: msgid "Windows" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:83 dongsheng@627: msgid "" dongsheng@627: "Lee Cantey publishes an installer of Mercurial for Windows at <ulink url=" dongsheng@627: "\"http://mercurial.berkwood.com\">http://mercurial.berkwood.com</ulink>. " dongsheng@627: "This package has no external dependencies; it <quote>just works</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:90 dongsheng@627: msgid "" dongsheng@627: "The Windows version of Mercurial does not automatically convert line endings " dongsheng@627: "between Windows and Unix styles. If you want to share work with Unix users, " dongsheng@627: "you must do a little additional configuration work. XXX Flesh this out." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:100 dongsheng@627: msgid "Getting started" dongsheng@627: msgstr "开始" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:102 dongsheng@627: msgid "" dongsheng@627: "To begin, we'll use the <command role=\"hg-cmd\">hg version</command> command " dongsheng@627: "to find out whether Mercurial is actually installed properly. The actual " dongsheng@627: "version information that it prints isn't so important; it's whether it prints " dongsheng@627: "anything at all that we care about." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:111 dongsheng@627: msgid "Built-in help" dongsheng@627: msgstr "内置帮助" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:113 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides a built-in help system. This is invaluable for those " dongsheng@627: "times when you find yourself stuck trying to remember how to run a command. " dongsheng@627: "If you are completely stuck, simply run <command role=\"hg-cmd\">hg help</" dongsheng@627: "command>; it will print a brief list of commands, along with a description of " dongsheng@627: "what each does. If you ask for help on a specific command (as below), it " dongsheng@627: "prints more detailed information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:124 dongsheng@627: msgid "" dongsheng@627: "For a more impressive level of detail (which you won't usually need) run " dongsheng@627: "<command role=\"hg-cmd\">hg help <option role=\"hg-opt-global\">-v</option></" dongsheng@627: "command>. The <option role=\"hg-opt-global\">-v</option> option is short for " dongsheng@627: "<option role=\"hg-opt-global\">--verbose</option>, and tells Mercurial to " dongsheng@627: "print more information than it usually would." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:135 dongsheng@627: msgid "Working with a repository" dongsheng@627: msgstr "使用版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:137 dongsheng@627: msgid "" dongsheng@627: "In Mercurial, everything happens inside a <emphasis>repository</emphasis>. " dongsheng@627: "The repository for a project contains all of the files that <quote>belong to</" dongsheng@627: "quote> that project, along with a historical record of the project's files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:143 dongsheng@627: msgid "" dongsheng@627: "There's nothing particularly magical about a repository; it is simply a " dongsheng@627: "directory tree in your filesystem that Mercurial treats as special. You can " dongsheng@627: "rename or delete a repository any time you like, using either the command " dongsheng@627: "line or your file browser." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:150 dongsheng@627: msgid "Making a local copy of a repository" dongsheng@627: msgstr "创建版本库的工作副本" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:152 dongsheng@627: msgid "" dongsheng@627: "<emphasis>Copying</emphasis> a repository is just a little bit special. " dongsheng@627: "While you could use a normal file copying command to make a copy of a " dongsheng@627: "repository, it's best to use a built-in command that Mercurial provides. " dongsheng@627: "This command is called <command role=\"hg-cmd\">hg clone</command>, because " dongsheng@627: "it creates an identical copy of an existing repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:161 dongsheng@627: msgid "" dongsheng@627: "If our clone succeeded, we should now have a local directory called <filename " dongsheng@627: "class=\"directory\">hello</filename>. This directory will contain some files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:167 dongsheng@627: msgid "" dongsheng@627: "These files have the same contents and history in our repository as they do " dongsheng@627: "in the repository we cloned." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:170 dongsheng@627: msgid "" dongsheng@627: "Every Mercurial repository is complete, self-contained, and independent. It " dongsheng@627: "contains its own private copy of a project's files and history. A cloned " dongsheng@627: "repository remembers the location of the repository it was cloned from, but " dongsheng@627: "it does not communicate with that repository, or any other, unless you tell " dongsheng@627: "it to." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:177 dongsheng@627: msgid "" dongsheng@627: "What this means for now is that we're free to experiment with our repository, " dongsheng@627: "safe in the knowledge that it's a private <quote>sandbox</quote> that won't " dongsheng@627: "affect anyone else." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:183 dongsheng@627: msgid "What's in a repository?" dongsheng@627: msgstr "什么是版本库?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:185 dongsheng@627: msgid "" dongsheng@627: "When we take a more detailed look inside a repository, we can see that it " dongsheng@627: "contains a directory named <filename class=\"directory\">.hg</filename>. " dongsheng@627: "This is where Mercurial keeps all of its metadata for the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:192 dongsheng@627: msgid "" dongsheng@627: "The contents of the <filename class=\"directory\">.hg</filename> directory " dongsheng@627: "and its subdirectories are private to Mercurial. Every other file and " dongsheng@627: "directory in the repository is yours to do with as you please." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:198 dongsheng@627: msgid "" dongsheng@627: "To introduce a little terminology, the <filename class=\"directory\">.hg</" dongsheng@627: "filename> directory is the <quote>real</quote> repository, and all of the " dongsheng@627: "files and directories that coexist with it are said to live in the " dongsheng@627: "<emphasis>working directory</emphasis>. An easy way to remember the " dongsheng@627: "distinction is that the <emphasis>repository</emphasis> contains the " dongsheng@627: "<emphasis>history</emphasis> of your project, while the <emphasis>working " dongsheng@627: "directory</emphasis> contains a <emphasis>snapshot</emphasis> of your project " dongsheng@627: "at a particular point in history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:213 dongsheng@627: msgid "A tour through history" dongsheng@627: msgstr "回溯历史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:215 dongsheng@627: msgid "" dongsheng@627: "One of the first things we might want to do with a new, unfamiliar repository " dongsheng@627: "is understand its history. The <command role=\"hg-cmd\">hg log</command> " dongsheng@627: "command gives us a view of history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:222 dongsheng@627: msgid "" dongsheng@627: "By default, this command prints a brief paragraph of output for each change " dongsheng@627: "to the project that was recorded. In Mercurial terminology, we call each of " dongsheng@627: "these recorded events a <emphasis>changeset</emphasis>, because it can " dongsheng@627: "contain a record of changes to several files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:228 dongsheng@627: msgid "" dongsheng@627: "The fields in a record of output from <command role=\"hg-cmd\">hg log</" dongsheng@627: "command> are as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:231 dongsheng@627: msgid "" dongsheng@627: "<literal>changeset</literal>: This field has the format of a number, followed " dongsheng@627: "by a colon, followed by a hexadecimal string. These are " dongsheng@627: "<emphasis>identifiers</emphasis> for the changeset. There are two " dongsheng@627: "identifiers because the number is shorter and easier to type than the hex " dongsheng@627: "string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:237 dongsheng@627: msgid "" dongsheng@627: "<literal>user</literal>: The identity of the person who created the " dongsheng@627: "changeset. This is a free-form field, but it most often contains a person's " dongsheng@627: "name and email address." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:241 dongsheng@627: msgid "" dongsheng@627: "<literal>date</literal>: The date and time on which the changeset was " dongsheng@627: "created, and the timezone in which it was created. (The date and time are " dongsheng@627: "local to that timezone; they display what time and date it was for the person " dongsheng@627: "who created the changeset.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:246 dongsheng@627: msgid "" dongsheng@627: "<literal>summary</literal>: The first line of the text message that the " dongsheng@627: "creator of the changeset entered to describe the changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:249 dongsheng@627: msgid "" dongsheng@627: "The default output printed by <command role=\"hg-cmd\">hg log</command> is " dongsheng@627: "purely a summary; it is missing a lot of detail." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:253 dongsheng@627: msgid "" dongsheng@627: "Figure <xref linkend=\"fig.tour-basic.history\"/> provides a graphical " dongsheng@627: "representation of the history of the <filename class=\"directory\">hello</" dongsheng@627: "filename> repository, to make it a little easier to see which direction " dongsheng@627: "history is <quote>flowing</quote> in. We'll be returning to this figure " dongsheng@627: "several times in this chapter and the chapter that follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject> dongsheng@627: #: ../en/ch02-tour-basic.xml:263 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-history.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><textobject><phrase> dongsheng@627: #: ../en/ch02-tour-basic.xml:264 ../en/ch03-tour-merge.xml:48 dongsheng@627: #: ../en/ch03-tour-merge.xml:76 ../en/ch03-tour-merge.xml:124 dongsheng@627: #: ../en/ch03-tour-merge.xml:181 ../en/ch03-tour-merge.xml:248 dongsheng@627: #: ../en/ch04-concepts.xml:54 ../en/ch04-concepts.xml:104 dongsheng@627: #: ../en/ch04-concepts.xml:189 ../en/ch04-concepts.xml:293 dongsheng@627: #: ../en/ch04-concepts.xml:342 ../en/ch04-concepts.xml:356 dongsheng@627: #: ../en/ch04-concepts.xml:396 ../en/ch04-concepts.xml:415 dongsheng@627: #: ../en/ch04-concepts.xml:456 ../en/ch06-collab.xml:275 dongsheng@627: #: ../en/ch09-undo.xml:363 ../en/ch09-undo.xml:411 ../en/ch09-undo.xml:476 dongsheng@627: #: ../en/ch09-undo.xml:516 ../en/ch12-mq.xml:408 dongsheng@627: msgid "XXX add text" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:265 dongsheng@627: msgid "" dongsheng@627: "Graphical history of the <filename class=\"directory\">hello</filename> " dongsheng@627: "repository" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:272 dongsheng@627: msgid "Changesets, revisions, and talking to other people" dongsheng@627: msgstr "改变集，版本，与其它用户交互" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:275 dongsheng@627: msgid "" dongsheng@627: "As English is a notoriously sloppy language, and computer science has a " dongsheng@627: "hallowed history of terminological confusion (why use one term when four will " dongsheng@627: "do?), revision control has a variety of words and phrases that mean the same " dongsheng@627: "thing. If you are talking about Mercurial history with other people, you " dongsheng@627: "will find that the word <quote>changeset</quote> is often compressed to " dongsheng@627: "<quote>change</quote> or (when written) <quote>cset</quote>, and sometimes a " dongsheng@627: "changeset is referred to as a <quote>revision</quote> or a <quote>rev</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:285 dongsheng@627: msgid "" dongsheng@627: "While it doesn't matter what <emphasis>word</emphasis> you use to refer to " dongsheng@627: "the concept of <quote>a changeset</quote>, the <emphasis>identifier</" dongsheng@627: "emphasis> that you use to refer to <quote>a <emphasis>specific</emphasis> " dongsheng@627: "changeset</quote> is of great importance. Recall that the <literal>changeset</" dongsheng@627: "literal> field in the output from <command role=\"hg-cmd\">hg log</command> " dongsheng@627: "identifies a changeset using both a number and a hexadecimal string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:294 dongsheng@627: msgid "" dongsheng@627: "The revision number is <emphasis>only valid in that repository</emphasis>," dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:296 dongsheng@627: msgid "" dongsheng@627: "while the hex string is the <emphasis>permanent, unchanging identifier</" dongsheng@627: "emphasis> that will always identify that exact changeset in <emphasis>every</" dongsheng@627: "emphasis> copy of the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:301 dongsheng@627: msgid "" dongsheng@627: "This distinction is important. If you send someone an email talking about " dongsheng@627: "<quote>revision 33</quote>, there's a high likelihood that their revision 33 " dongsheng@627: "will <emphasis>not be the same</emphasis> as yours. The reason for this is " dongsheng@627: "that a revision number depends on the order in which changes arrived in a " dongsheng@627: "repository, and there is no guarantee that the same changes will happen in " dongsheng@627: "the same order in different repositories. Three changes $a,b,c$ can easily " dongsheng@627: "appear in one repository as $0,1,2$, while in another as $1,0,2$." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:311 dongsheng@627: msgid "" dongsheng@627: "Mercurial uses revision numbers purely as a convenient shorthand. If you " dongsheng@627: "need to discuss a changeset with someone, or make a record of a changeset for " dongsheng@627: "some other reason (for example, in a bug report), use the hexadecimal " dongsheng@627: "identifier." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:319 dongsheng@627: msgid "Viewing specific revisions" dongsheng@627: msgstr "察看指定版本" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:321 dongsheng@627: msgid "" dongsheng@627: "To narrow the output of <command role=\"hg-cmd\">hg log</command> down to a " dongsheng@627: "single revision, use the <option role=\"hg-opt-log\">-r</option> (or <option " dongsheng@627: "role=\"hg-opt-log\">--rev</option>) option. You can use either a revision " dongsheng@627: "number or a long-form changeset identifier, and you can provide as many " dongsheng@627: "revisions as you want." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:330 dongsheng@627: msgid "" dongsheng@627: "If you want to see the history of several revisions without having to list " dongsheng@627: "each one, you can use <emphasis>range notation</emphasis>; this lets you " dongsheng@627: "express the idea <quote>I want all revisions between <literal>abc</literal> " dongsheng@627: "and <literal>def</literal>, inclusive</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:338 dongsheng@627: msgid "" dongsheng@627: "Mercurial also honours the order in which you specify revisions, so <command " dongsheng@627: "role=\"hg-cmd\">hg log -r 2:4</command> prints 2, 3, and 4. while <command " dongsheng@627: "role=\"hg-cmd\">hg log -r 4:2</command> prints 4, 3, and 2." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:345 dongsheng@627: msgid "More detailed information" dongsheng@627: msgstr "更详细的信息" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:347 dongsheng@627: msgid "" dongsheng@627: "While the summary information printed by <command role=\"hg-cmd\">hg log</" dongsheng@627: "command> is useful if you already know what you're looking for, you may need " dongsheng@627: "to see a complete description of the change, or a list of the files changed, " dongsheng@627: "if you're trying to decide whether a changeset is the one you're looking for. " dongsheng@627: "The <command role=\"hg-cmd\">hg log</command> command's <option role=\"hg-opt-" dongsheng@627: "global\">-v</option> (or <option role=\"hg-opt-global\">--verbose</option>) " dongsheng@627: "option gives you this extra detail." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:359 dongsheng@627: msgid "" dongsheng@627: "If you want to see both the description and content of a change, add the " dongsheng@627: "<option role=\"hg-opt-log\">-p</option> (or <option role=\"hg-opt-log\">--" dongsheng@627: "patch</option>) option. This displays the content of a change as a " dongsheng@627: "<emphasis>unified diff</emphasis> (if you've never seen a unified diff " dongsheng@627: "before, see section <xref linkend=\"sec.mq.patch\"/> for an overview)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:372 dongsheng@627: msgid "All about command options" dongsheng@627: msgstr "命令选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:374 dongsheng@627: msgid "" dongsheng@627: "Let's take a brief break from exploring Mercurial commands to discuss a " dongsheng@627: "pattern in the way that they work; you may find this useful to keep in mind " dongsheng@627: "as we continue our tour." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:378 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a consistent and straightforward approach to dealing with the " dongsheng@627: "options that you can pass to commands. It follows the conventions for " dongsheng@627: "options that are common to modern Linux and Unix systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:383 dongsheng@627: msgid "" dongsheng@627: "Every option has a long name. For example, as we've already seen, the " dongsheng@627: "<command role=\"hg-cmd\">hg log</command> command accepts a <option role=\"hg-" dongsheng@627: "opt-log\">--rev</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:387 dongsheng@627: msgid "" dongsheng@627: "Most options have short names, too. Instead of <option role=\"hg-opt-log\">--" dongsheng@627: "rev</option>, we can use <option role=\"hg-opt-log\">-r</option>. (The " dongsheng@627: "reason that some options don't have short names is that the options in " dongsheng@627: "question are rarely used.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:392 dongsheng@627: msgid "" dongsheng@627: "Long options start with two dashes (e.g. <option role=\"hg-opt-log\">--rev</" dongsheng@627: "option>), while short options start with one (e.g. <option role=\"hg-opt-log" dongsheng@627: "\">-r</option>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:396 dongsheng@627: msgid "" dongsheng@627: "Option naming and usage is consistent across commands. For example, every " dongsheng@627: "command that lets you specify a changeset ID or revision number accepts both " dongsheng@627: "<option role=\"hg-opt-log\">-r</option> and <option role=\"hg-opt-log\">--" dongsheng@627: "rev</option> arguments." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:402 dongsheng@627: msgid "" dongsheng@627: "In the examples throughout this book, I use short options instead of long. " dongsheng@627: "This just reflects my own preference, so don't read anything significant into " dongsheng@627: "it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:406 dongsheng@627: msgid "" dongsheng@627: "Most commands that print output of some kind will print more output when " dongsheng@627: "passed a <option role=\"hg-opt-global\">-v</option> (or <option role=\"hg-opt-" dongsheng@627: "global\">--verbose</option>) option, and less when passed <option role=\"hg-" dongsheng@627: "opt-global\">-q</option> (or <option role=\"hg-opt-global\">--quiet</option>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:414 dongsheng@627: msgid "Making and reviewing changes" dongsheng@627: msgstr "创建和复审修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:416 dongsheng@627: msgid "" dongsheng@627: "Now that we have a grasp of viewing history in Mercurial, let's take a look " dongsheng@627: "at making some changes and examining them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:420 dongsheng@627: msgid "" dongsheng@627: "The first thing we'll do is isolate our experiment in a repository of its " dongsheng@627: "own. We use the <command role=\"hg-cmd\">hg clone</command> command, but we " dongsheng@627: "don't need to clone a copy of the remote repository. Since we already have a " dongsheng@627: "copy of it locally, we can just clone that instead. This is much faster than " dongsheng@627: "cloning over the network, and cloning a local repository uses less disk space " dongsheng@627: "in most cases, too." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:430 dongsheng@627: msgid "" dongsheng@627: "As an aside, it's often good practice to keep a <quote>pristine</quote> copy " dongsheng@627: "of a remote repository around, which you can then make temporary clones of to " dongsheng@627: "create sandboxes for each task you want to work on. This lets you work on " dongsheng@627: "multiple tasks in parallel, each isolated from the others until it's complete " dongsheng@627: "and you're ready to integrate it back. Because local clones are so cheap, " dongsheng@627: "there's almost no overhead to cloning and destroying repositories whenever " dongsheng@627: "you want." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:439 dongsheng@627: msgid "" dongsheng@627: "In our <filename class=\"directory\">my-hello</filename> repository, we have " dongsheng@627: "a file <filename>hello.c</filename> that contains the classic <quote>hello, " dongsheng@627: "world</quote> program. Let's use the ancient and venerable <command>sed</" dongsheng@627: "command> command to edit this file so that it prints a second line of " dongsheng@627: "output. (I'm only using <command>sed</command> to do this because it's easy " dongsheng@627: "to write a scripted example this way. Since you're not under the same " dongsheng@627: "constraint, you probably won't want to use <command>sed</command>; simply use " dongsheng@627: "your preferred text editor to do the same thing.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:452 dongsheng@627: msgid "" dongsheng@627: "Mercurial's <command role=\"hg-cmd\">hg status</command> command will tell us " dongsheng@627: "what Mercurial knows about the files in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:458 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg status</command> command prints no output for " dongsheng@627: "some files, but a line starting with <quote><literal>M</literal></quote> for " dongsheng@627: "<filename>hello.c</filename>. Unless you tell it to, <command role=\"hg-cmd" dongsheng@627: "\">hg status</command> will not print any output for files that have not been " dongsheng@627: "modified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:465 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>M</literal></quote> indicates that Mercurial has noticed " dongsheng@627: "that we modified <filename>hello.c</filename>. We didn't need to " dongsheng@627: "<emphasis>inform</emphasis> Mercurial that we were going to modify the file " dongsheng@627: "before we started, or that we had modified the file after we were done; it " dongsheng@627: "was able to figure this out itself." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:473 dongsheng@627: msgid "" dongsheng@627: "It's a little bit helpful to know that we've modified <filename>hello.c</" dongsheng@627: "filename>, but we might prefer to know exactly <emphasis>what</emphasis> " dongsheng@627: "changes we've made to it. To do this, we use the <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:483 dongsheng@627: msgid "Recording changes in a new changeset" dongsheng@627: msgstr "在新修改集中记录修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:485 dongsheng@627: msgid "" dongsheng@627: "We can modify files, build and test our changes, and use <command role=\"hg-" dongsheng@627: "cmd\">hg status</command> and <command role=\"hg-cmd\">hg diff</command> to " dongsheng@627: "review our changes, until we're satisfied with what we've done and arrive at " dongsheng@627: "a natural stopping point where we want to record our work in a new changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:492 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg commit</command> command lets us create a new " dongsheng@627: "changeset; we'll usually refer to this as <quote>making a commit</quote> or " dongsheng@627: "<quote>committing</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:498 dongsheng@627: msgid "Setting up a username" dongsheng@627: msgstr "配置用户名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:500 dongsheng@627: msgid "" dongsheng@627: "When you try to run <command role=\"hg-cmd\">hg commit</command> for the " dongsheng@627: "first time, it is not guaranteed to succeed. Mercurial records your name and " dongsheng@627: "address with each change that you commit, so that you and others will later " dongsheng@627: "be able to tell who made each change. Mercurial tries to automatically " dongsheng@627: "figure out a sensible username to commit the change with. It will attempt " dongsheng@627: "each of the following methods, in order:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:509 dongsheng@627: msgid "" dongsheng@627: "If you specify a <option role=\"hg-opt-commit\">-u</option> option to the " dongsheng@627: "<command role=\"hg-cmd\">hg commit</command> command on the command line, " dongsheng@627: "followed by a username, this is always given the highest precedence." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:514 dongsheng@627: msgid "" dongsheng@627: "If you have set the <envar>HGUSER</envar> environment variable, this is " dongsheng@627: "checked next." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:517 dongsheng@627: msgid "" dongsheng@627: "If you create a file in your home directory called <filename role=\"special" dongsheng@627: "\">.hgrc</filename>, with a <envar role=\"rc-item-ui\">username</envar> " dongsheng@627: "entry, that will be used next. To see what the contents of this file should " dongsheng@627: "look like, refer to section <xref linkend=\"sec.tour-basic.username\"/> below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:524 dongsheng@627: msgid "" dongsheng@627: "If you have set the <envar>EMAIL</envar> environment variable, this will be " dongsheng@627: "used next." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:527 dongsheng@627: msgid "" dongsheng@627: "Mercurial will query your system to find out your local user name and host " dongsheng@627: "name, and construct a username from these components. Since this often " dongsheng@627: "results in a username that is not very useful, it will print a warning if it " dongsheng@627: "has to do this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:534 dongsheng@627: msgid "" dongsheng@627: "If all of these mechanisms fail, Mercurial will fail, printing an error " dongsheng@627: "message. In this case, it will not let you commit until you set up a " dongsheng@627: "username." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:538 dongsheng@627: msgid "" dongsheng@627: "You should think of the <envar>HGUSER</envar> environment variable and the " dongsheng@627: "<option role=\"hg-opt-commit\">-u</option> option to the <command role=\"hg-" dongsheng@627: "cmd\">hg commit</command> command as ways to <emphasis>override</emphasis> " dongsheng@627: "Mercurial's default selection of username. For normal use, the simplest and " dongsheng@627: "most robust way to set a username for yourself is by creating a <filename " dongsheng@627: "role=\"special\">.hgrc</filename> file; see below for details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:547 dongsheng@627: msgid "Creating a Mercurial configuration file" dongsheng@627: msgstr "创建 Mercurial 的配置文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:549 dongsheng@627: msgid "" dongsheng@627: "To set a user name, use your favourite editor to create a file called " dongsheng@627: "<filename role=\"special\">.hgrc</filename> in your home directory. " dongsheng@627: "Mercurial will use this file to look up your personalised configuration " dongsheng@627: "settings. The initial contents of your <filename role=\"special\">.hgrc</" dongsheng@627: "filename> should look like this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:560 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>[ui]</literal></quote> line begins a <emphasis>section</" dongsheng@627: "emphasis> of the config file, so you can read the <quote><literal>username " dongsheng@627: "= ...</literal></quote> line as meaning <quote>set the value of the " dongsheng@627: "<literal>username</literal> item in the <literal>ui</literal> section</" dongsheng@627: "quote>. A section continues until a new section begins, or the end of the " dongsheng@627: "file. Mercurial ignores empty lines and treats any text from " dongsheng@627: "<quote><literal>#</literal></quote> to the end of a line as a comment." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:573 dongsheng@627: msgid "Choosing a user name" dongsheng@627: msgstr "选择用户名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:575 dongsheng@627: msgid "" dongsheng@627: "You can use any text you like as the value of the <literal>username</literal> " dongsheng@627: "config item, since this information is for reading by other people, but for " dongsheng@627: "interpreting by Mercurial. The convention that most people follow is to use " dongsheng@627: "their name and email address, as in the example above." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><note><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:582 dongsheng@627: msgid "" dongsheng@627: "Mercurial's built-in web server obfuscates email addresses, to make it more " dongsheng@627: "difficult for the email harvesting tools that spammers use. This reduces the " dongsheng@627: "likelihood that you'll start receiving more junk email if you publish a " dongsheng@627: "Mercurial repository on the web." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:592 dongsheng@627: msgid "Writing a commit message" dongsheng@627: msgstr "写提交日志" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:594 dongsheng@627: msgid "" dongsheng@627: "When we commit a change, Mercurial drops us into a text editor, to enter a " dongsheng@627: "message that will describe the modifications we've made in this changeset. " dongsheng@627: "This is called the <emphasis>commit message</emphasis>. It will be a record " dongsheng@627: "for readers of what we did and why, and it will be printed by <command role=" dongsheng@627: "\"hg-cmd\">hg log</command> after we've finished committing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:604 dongsheng@627: msgid "" dongsheng@627: "The editor that the <command role=\"hg-cmd\">hg commit</command> command " dongsheng@627: "drops us into will contain an empty line, followed by a number of lines " dongsheng@627: "starting with <quote><literal>HG:</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:611 dongsheng@627: msgid "" dongsheng@627: "Mercurial ignores the lines that start with <quote><literal>HG:</literal></" dongsheng@627: "quote>; it uses them only to tell us which files it's recording changes to. " dongsheng@627: "Modifying or deleting these lines has no effect." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:617 dongsheng@627: msgid "Writing a good commit message" dongsheng@627: msgstr "写好提交日志" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:619 dongsheng@627: msgid "" dongsheng@627: "Since <command role=\"hg-cmd\">hg log</command> only prints the first line of " dongsheng@627: "a commit message by default, it's best to write a commit message whose first " dongsheng@627: "line stands alone. Here's a real example of a commit message that " dongsheng@627: "<emphasis>doesn't</emphasis> follow this guideline, and hence has a summary " dongsheng@627: "that is not readable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:633 dongsheng@627: msgid "" dongsheng@627: "As far as the remainder of the contents of the commit message are concerned, " dongsheng@627: "there are no hard-and-fast rules. Mercurial itself doesn't interpret or care " dongsheng@627: "about the contents of the commit message, though your project may have " dongsheng@627: "policies that dictate a certain kind of formatting." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:639 dongsheng@627: msgid "" dongsheng@627: "My personal preference is for short, but informative, commit messages that " dongsheng@627: "tell me something that I can't figure out with a quick glance at the output " dongsheng@627: "of <command role=\"hg-cmd\">hg log --patch</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:646 dongsheng@627: msgid "Aborting a commit" dongsheng@627: msgstr "终止提交" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:648 dongsheng@627: msgid "" dongsheng@627: "If you decide that you don't want to commit while in the middle of editing a " dongsheng@627: "commit message, simply exit from your editor without saving the file that " dongsheng@627: "it's editing. This will cause nothing to happen to either the repository or " dongsheng@627: "the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:653 dongsheng@627: msgid "" dongsheng@627: "If we run the <command role=\"hg-cmd\">hg commit</command> command without " dongsheng@627: "any arguments, it records all of the changes we've made, as reported by " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> and <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:660 dongsheng@627: msgid "Admiring our new handiwork" dongsheng@627: msgstr "欣赏我们的新手艺" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:662 dongsheng@627: msgid "" dongsheng@627: "Once we've finished the commit, we can use the <command role=\"hg-cmd\">hg " dongsheng@627: "tip</command> command to display the changeset we just created. This command " dongsheng@627: "produces output that is identical to <command role=\"hg-cmd\">hg log</" dongsheng@627: "command>, but it only displays the newest revision in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:671 dongsheng@627: msgid "" dongsheng@627: "We refer to the newest revision in the repository as the tip revision, or " dongsheng@627: "simply the tip." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:678 dongsheng@627: msgid "Sharing changes" dongsheng@627: msgstr "共享修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:680 dongsheng@627: msgid "" dongsheng@627: "We mentioned earlier that repositories in Mercurial are self-contained. This " dongsheng@627: "means that the changeset we just created exists only in our <filename class=" dongsheng@627: "\"directory\">my-hello</filename> repository. Let's look at a few ways that " dongsheng@627: "we can propagate this change into other repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:688 dongsheng@627: msgid "Pulling changes from another repository" dongsheng@627: msgstr "从其它版本库取得修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:689 dongsheng@627: msgid "" dongsheng@627: "To get started, let's clone our original <filename class=\"directory\">hello</" dongsheng@627: "filename> repository, which does not contain the change we just committed. " dongsheng@627: "We'll call our temporary repository <filename class=\"directory\">hello-pull</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:697 dongsheng@627: msgid "" dongsheng@627: "We'll use the <command role=\"hg-cmd\">hg pull</command> command to bring " dongsheng@627: "changes from <filename class=\"directory\">my-hello</filename> into <filename " dongsheng@627: "class=\"directory\">hello-pull</filename>. However, blindly pulling unknown " dongsheng@627: "changes into a repository is a somewhat scary prospect. Mercurial provides " dongsheng@627: "the <command role=\"hg-cmd\">hg incoming</command> command to tell us what " dongsheng@627: "changes the <command role=\"hg-cmd\">hg pull</command> command " dongsheng@627: "<emphasis>would</emphasis> pull into the repository, without actually pulling " dongsheng@627: "the changes in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:710 dongsheng@627: msgid "" dongsheng@627: "(Of course, someone could cause more changesets to appear in the repository " dongsheng@627: "that we ran <command role=\"hg-cmd\">hg incoming</command> in, before we get " dongsheng@627: "a chance to <command role=\"hg-cmd\">hg pull</command> the changes, so that " dongsheng@627: "we could end up pulling changes that we didn't expect.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:717 dongsheng@627: msgid "" dongsheng@627: "Bringing changes into a repository is a simple matter of running the <command " dongsheng@627: "role=\"hg-cmd\">hg pull</command> command, and telling it which repository to " dongsheng@627: "pull from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:724 dongsheng@627: msgid "" dongsheng@627: "As you can see from the before-and-after output of <command role=\"hg-cmd" dongsheng@627: "\">hg tip</command>, we have successfully pulled changes into our " dongsheng@627: "repository. There remains one step before we can see these changes in the " dongsheng@627: "working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:732 dongsheng@627: msgid "Updating the working directory" dongsheng@627: msgstr "更新工作目录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:734 dongsheng@627: msgid "" dongsheng@627: "We have so far glossed over the relationship between a repository and its " dongsheng@627: "working directory. The <command role=\"hg-cmd\">hg pull</command> command " dongsheng@627: "that we ran in section <xref linkend=\"sec.tour.pull\"/> brought changes into " dongsheng@627: "the repository, but if we check, there's no sign of those changes in the " dongsheng@627: "working directory. This is because <command role=\"hg-cmd\">hg pull</" dongsheng@627: "command> does not (by default) touch the working directory. Instead, we use " dongsheng@627: "the <command role=\"hg-cmd\">hg update</command> command to do this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:746 dongsheng@627: msgid "" dongsheng@627: "It might seem a bit strange that <command role=\"hg-cmd\">hg pull</command> " dongsheng@627: "doesn't update the working directory automatically. There's actually a good " dongsheng@627: "reason for this: you can use <command role=\"hg-cmd\">hg update</command> to " dongsheng@627: "update the working directory to the state it was in at <emphasis>any " dongsheng@627: "revision</emphasis> in the history of the repository. If you had the working " dongsheng@627: "directory updated to an old revision---to hunt down the origin of a bug, " dongsheng@627: "say---and ran a <command role=\"hg-cmd\">hg pull</command> which " dongsheng@627: "automatically updated the working directory to a new revision, you might not " dongsheng@627: "be terribly happy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:757 dongsheng@627: msgid "" dongsheng@627: "However, since pull-then-update is such a common thing to do, Mercurial lets " dongsheng@627: "you combine the two by passing the <option role=\"hg-opt-pull\">-u</option> " dongsheng@627: "option to <command role=\"hg-cmd\">hg pull</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:762 dongsheng@627: msgid "" dongsheng@627: "If you look back at the output of <command role=\"hg-cmd\">hg pull</command> " dongsheng@627: "in section <xref linkend=\"sec.tour.pull\"/> when we ran it without <option " dongsheng@627: "role=\"hg-opt-pull\">-u</option>, you can see that it printed a helpful " dongsheng@627: "reminder that we'd have to take an explicit step to update the working " dongsheng@627: "directory:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:771 dongsheng@627: msgid "" dongsheng@627: "To find out what revision the working directory is at, use the <command role=" dongsheng@627: "\"hg-cmd\">hg parents</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:777 dongsheng@627: msgid "" dongsheng@627: "If you look back at figure <xref linkend=\"fig.tour-basic.history\"/>, you'll " dongsheng@627: "see arrows connecting each changeset. The node that the arrow leads " dongsheng@627: "<emphasis>from</emphasis> in each case is a parent, and the node that the " dongsheng@627: "arrow leads <emphasis>to</emphasis> is its child. The working directory has " dongsheng@627: "a parent in just the same way; this is the changeset that the working " dongsheng@627: "directory currently contains." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:786 dongsheng@627: msgid "" dongsheng@627: "To update the working directory to a particular revision, give a revision " dongsheng@627: "number or changeset ID to the <command role=\"hg-cmd\">hg update</command> " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:793 dongsheng@627: msgid "" dongsheng@627: "If you omit an explicit revision, <command role=\"hg-cmd\">hg update</" dongsheng@627: "command> will update to the tip revision, as shown by the second call to " dongsheng@627: "<command role=\"hg-cmd\">hg update</command> in the example above." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:801 dongsheng@627: msgid "Pushing changes to another repository" dongsheng@627: msgstr "发布修改到其它版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:803 dongsheng@627: msgid "" dongsheng@627: "Mercurial lets us push changes to another repository, from the repository " dongsheng@627: "we're currently visiting. As with the example of <command role=\"hg-cmd\">hg " dongsheng@627: "pull</command> above, we'll create a temporary repository to push our changes " dongsheng@627: "into." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:811 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg outgoing</command> command tells us what " dongsheng@627: "changes would be pushed into another repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:817 dongsheng@627: msgid "" dongsheng@627: "And the <command role=\"hg-cmd\">hg push</command> command does the actual " dongsheng@627: "push." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:823 dongsheng@627: msgid "" dongsheng@627: "As with <command role=\"hg-cmd\">hg pull</command>, the <command role=\"hg-cmd" dongsheng@627: "\">hg push</command> command does not update the working directory in the " dongsheng@627: "repository that it's pushing changes into. (Unlike <command role=\"hg-cmd" dongsheng@627: "\">hg pull</command>, <command role=\"hg-cmd\">hg push</command> does not " dongsheng@627: "provide a <literal>-u</literal> option that updates the other repository's " dongsheng@627: "working directory.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:832 dongsheng@627: msgid "" dongsheng@627: "What happens if we try to pull or push changes and the receiving repository " dongsheng@627: "already has those changes? Nothing too exciting." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch02-tour-basic.xml:839 dongsheng@627: msgid "Sharing changes over a network" dongsheng@627: msgstr "通过网络共享修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:841 dongsheng@627: msgid "" dongsheng@627: "The commands we have covered in the previous few sections are not limited to " dongsheng@627: "working with local repositories. Each works in exactly the same fashion over " dongsheng@627: "a network connection; simply pass in a URL instead of a local path." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch02-tour-basic.xml:849 dongsheng@627: msgid "" dongsheng@627: "In this example, we can see what changes we could push to the remote " dongsheng@627: "repository, but the repository is understandably not set up to let anonymous " dongsheng@627: "users push to it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:5 dongsheng@627: msgid "A tour of Mercurial: merging work" dongsheng@627: msgstr "Mercurial 教程: 合并工作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:7 dongsheng@627: msgid "" dongsheng@627: "We've now covered cloning a repository, making changes in a repository, and " dongsheng@627: "pulling or pushing changes from one repository into another. Our next step " dongsheng@627: "is <emphasis>merging</emphasis> changes from separate repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:13 dongsheng@627: msgid "Merging streams of work" dongsheng@627: msgstr "合并的流程" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:15 dongsheng@627: msgid "" dongsheng@627: "Merging is a fundamental part of working with a distributed revision control " dongsheng@627: "tool." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:18 dongsheng@627: msgid "" dongsheng@627: "Alice and Bob each have a personal copy of a repository for a project they're " dongsheng@627: "collaborating on. Alice fixes a bug in her repository; Bob adds a new " dongsheng@627: "feature in his. They want the shared repository to contain both the bug fix " dongsheng@627: "and the new feature." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:24 dongsheng@627: msgid "" dongsheng@627: "I frequently work on several different tasks for a single project at once, " dongsheng@627: "each safely isolated in its own repository. Working this way means that I " dongsheng@627: "often need to merge one piece of my own work with another." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:30 dongsheng@627: msgid "" dongsheng@627: "Because merging is such a common thing to need to do, Mercurial makes it " dongsheng@627: "easy. Let's walk through the process. We'll begin by cloning yet another " dongsheng@627: "repository (see how often they spring up?) and making a change in it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:37 dongsheng@627: msgid "" dongsheng@627: "We should now have two copies of <filename>hello.c</filename> with different " dongsheng@627: "contents. The histories of the two repositories have also diverged, as " dongsheng@627: "illustrated in figure <xref linkend=\"fig.tour-merge.sep-repos\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:47 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-merge-sep-repos.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:49 dongsheng@627: msgid "" dongsheng@627: "Divergent recent histories of the <filename class=\"directory\">my-hello</" dongsheng@627: "filename> and <filename class=\"directory\">my-new-hello</filename> " dongsheng@627: "repositories" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:56 dongsheng@627: msgid "" dongsheng@627: "We already know that pulling changes from our <filename class=\"directory" dongsheng@627: "\">my-hello</filename> repository will have no effect on the working " dongsheng@627: "directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:62 dongsheng@627: msgid "" dongsheng@627: "However, the <command role=\"hg-cmd\">hg pull</command> command says " dongsheng@627: "something about <quote>heads</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:66 dongsheng@627: msgid "Head changesets" dongsheng@627: msgstr "顶点改变集" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:68 dongsheng@627: msgid "" dongsheng@627: "A head is a change that has no descendants, or children, as they're also " dongsheng@627: "known. The tip revision is thus a head, because the newest revision in a " dongsheng@627: "repository doesn't have any children, but a repository can contain more than " dongsheng@627: "one head." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:75 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-merge-pull.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:78 dongsheng@627: msgid "" dongsheng@627: "Repository contents after pulling from <filename class=\"directory\">my-" dongsheng@627: "hello</filename> into <filename class=\"directory\">my-new-hello</filename>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:85 dongsheng@627: msgid "" dongsheng@627: "In figure <xref linkend=\"fig.tour-merge.pull\"/>, you can see the effect of " dongsheng@627: "the pull from <filename class=\"directory\">my-hello</filename> into " dongsheng@627: "<filename class=\"directory\">my-new-hello</filename>. The history that was " dongsheng@627: "already present in <filename class=\"directory\">my-new-hello</filename> is " dongsheng@627: "untouched, but a new revision has been added. By referring to figure <xref " dongsheng@627: "linkend=\"fig.tour-merge.sep-repos\"/>, we can see that the " dongsheng@627: "<emphasis>changeset ID</emphasis> remains the same in the new repository, but " dongsheng@627: "the <emphasis>revision number</emphasis> has changed. (This, incidentally, " dongsheng@627: "is a fine example of why it's not safe to use revision numbers when " dongsheng@627: "discussing changesets.) We can view the heads in a repository using the " dongsheng@627: "<command role=\"hg-cmd\">hg heads</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:104 dongsheng@627: msgid "Performing the merge" dongsheng@627: msgstr "执行合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:106 dongsheng@627: msgid "" dongsheng@627: "What happens if we try to use the normal <command role=\"hg-cmd\">hg update</" dongsheng@627: "command> command to update to the new tip?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:112 dongsheng@627: msgid "" dongsheng@627: "Mercurial is telling us that the <command role=\"hg-cmd\">hg update</command> " dongsheng@627: "command won't do a merge; it won't update the working directory when it " dongsheng@627: "thinks we might be wanting to do a merge, unless we force it to do so. " dongsheng@627: "Instead, we use the <command role=\"hg-cmd\">hg merge</command> command to " dongsheng@627: "merge the two heads." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:123 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-merge-merge.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:126 dongsheng@627: msgid "Working directory and repository during merge, and following commit" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:131 dongsheng@627: msgid "" dongsheng@627: "This updates the working directory so that it contains changes from " dongsheng@627: "<emphasis>both</emphasis> heads, which is reflected in both the output of " dongsheng@627: "<command role=\"hg-cmd\">hg parents</command> and the contents of " dongsheng@627: "<filename>hello.c</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:141 dongsheng@627: msgid "Committing the results of the merge" dongsheng@627: msgstr "提交合并结果" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:143 dongsheng@627: msgid "" dongsheng@627: "Whenever we've done a merge, <command role=\"hg-cmd\">hg parents</command> " dongsheng@627: "will display two parents until we <command role=\"hg-cmd\">hg commit</" dongsheng@627: "command> the results of the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:150 dongsheng@627: msgid "" dongsheng@627: "We now have a new tip revision; notice that it has <emphasis>both</emphasis> " dongsheng@627: "of our former heads as its parents. These are the same revisions that were " dongsheng@627: "previously displayed by <command role=\"hg-cmd\">hg parents</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:157 dongsheng@627: msgid "" dongsheng@627: "In figure <xref linkend=\"fig.tour-merge.merge\"/>, you can see a " dongsheng@627: "representation of what happens to the working directory during the merge, and " dongsheng@627: "how this affects the repository when the commit happens. During the merge, " dongsheng@627: "the working directory has two parent changesets, and these become the parents " dongsheng@627: "of the new changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:168 dongsheng@627: msgid "Merging conflicting changes" dongsheng@627: msgstr "合并有冲突的改变" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:170 dongsheng@627: msgid "" dongsheng@627: "Most merges are simple affairs, but sometimes you'll find yourself merging " dongsheng@627: "changes where each modifies the same portions of the same files. Unless both " dongsheng@627: "modifications are identical, this results in a <emphasis>conflict</emphasis>, " dongsheng@627: "where you have to decide how to reconcile the different changes into " dongsheng@627: "something coherent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:180 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/tour-merge-conflict.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:182 dongsheng@627: msgid "Conflicting changes to a document" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:186 dongsheng@627: msgid "" dongsheng@627: "Figure <xref linkend=\"fig.tour-merge.conflict\"/> illustrates an instance of " dongsheng@627: "two conflicting changes to a document. We started with a single version of " dongsheng@627: "the file; then we made some changes; while someone else made different " dongsheng@627: "changes to the same text. Our task in resolving the conflicting changes is " dongsheng@627: "to decide what the file should look like." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:193 dongsheng@627: msgid "" dongsheng@627: "Mercurial doesn't have a built-in facility for handling conflicts. Instead, " dongsheng@627: "it runs an external program called <command>hgmerge</command>. This is a " dongsheng@627: "shell script that is bundled with Mercurial; you can change it to behave " dongsheng@627: "however you please. What it does by default is try to find one of several " dongsheng@627: "different merging tools that are likely to be installed on your system. It " dongsheng@627: "first tries a few fully automatic merging tools; if these don't succeed " dongsheng@627: "(because the resolution process requires human guidance) or aren't present, " dongsheng@627: "the script tries a few different graphical merging tools." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:204 dongsheng@627: msgid "" dongsheng@627: "It's also possible to get Mercurial to run another program or script instead " dongsheng@627: "of <command>hgmerge</command>, by setting the <envar>HGMERGE</envar> " dongsheng@627: "environment variable to the name of your preferred program." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:210 dongsheng@627: msgid "Using a graphical merge tool" dongsheng@627: msgstr "使用图形合并工具" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:212 dongsheng@627: msgid "" dongsheng@627: "My preferred graphical merge tool is <command>kdiff3</command>, which I'll " dongsheng@627: "use to describe the features that are common to graphical file merging " dongsheng@627: "tools. You can see a screenshot of <command>kdiff3</command> in action in " dongsheng@627: "figure <xref linkend=\"fig.tour-merge.kdiff3\"/>. The kind of merge it is " dongsheng@627: "performing is called a <emphasis>three-way merge</emphasis>, because there " dongsheng@627: "are three different versions of the file of interest to us. The tool thus " dongsheng@627: "splits the upper portion of the window into three panes:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:222 dongsheng@627: msgid "" dongsheng@627: "At the left is the <emphasis>base</emphasis> version of the file, i.e. the " dongsheng@627: "most recent version from which the two versions we're trying to merge are " dongsheng@627: "descended." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:227 dongsheng@627: msgid "" dongsheng@627: "In the middle is <quote>our</quote> version of the file, with the contents " dongsheng@627: "that we modified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:230 dongsheng@627: msgid "" dongsheng@627: "On the right is <quote>their</quote> version of the file, the one that from " dongsheng@627: "the changeset that we're trying to merge with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:234 dongsheng@627: msgid "" dongsheng@627: "In the pane below these is the current <emphasis>result</emphasis> of the " dongsheng@627: "merge. Our task is to replace all of the red text, which indicates unresolved " dongsheng@627: "conflicts, with some sensible merger of the <quote>ours</quote> and " dongsheng@627: "<quote>theirs</quote> versions of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:241 dongsheng@627: msgid "" dongsheng@627: "All four of these panes are <emphasis>locked together</emphasis>; if we " dongsheng@627: "scroll vertically or horizontally in any of them, the others are updated to " dongsheng@627: "display the corresponding sections of their respective files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch03-tour-merge.xml:247 dongsheng@630: msgid "" dongsheng@630: "<imageobject><imagedata width=\"100%\" fileref=\"images/kdiff3.png\"/></" dongsheng@630: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:250 dongsheng@627: msgid "Using <command>kdiff3</command> to merge versions of a file" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:255 dongsheng@627: msgid "" dongsheng@627: "For each conflicting portion of the file, we can choose to resolve the " dongsheng@627: "conflict using some combination of text from the base version, ours, or " dongsheng@627: "theirs. We can also manually edit the merged file at any time, in case we " dongsheng@627: "need to make further modifications." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:261 dongsheng@627: msgid "" dongsheng@627: "There are <emphasis>many</emphasis> file merging tools available, too many to " dongsheng@627: "cover here. They vary in which platforms they are available for, and in " dongsheng@627: "their particular strengths and weaknesses. Most are tuned for merging files " dongsheng@627: "containing plain text, while a few are aimed at specialised file formats " dongsheng@627: "(generally XML)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:270 dongsheng@627: msgid "A worked example" dongsheng@627: msgstr "合并实例" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:272 dongsheng@627: msgid "" dongsheng@627: "In this example, we will reproduce the file modification history of figure " dongsheng@627: "<xref linkend=\"fig.tour-merge.conflict\"/> above. Let's begin by creating a " dongsheng@627: "repository with a base version of our document." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:279 dongsheng@627: msgid "We'll clone the repository and make a change to the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:284 dongsheng@627: msgid "" dongsheng@627: "And another clone, to simulate someone else making a change to the file. " dongsheng@627: "(This hints at the idea that it's not all that unusual to merge with yourself " dongsheng@627: "when you isolate tasks in separate repositories, and indeed to find and " dongsheng@627: "resolve conflicts while doing so.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:292 dongsheng@627: msgid "" dongsheng@627: "Having created two different versions of the file, we'll set up an " dongsheng@627: "environment suitable for running our merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:298 dongsheng@627: msgid "" dongsheng@627: "In this example, I won't use Mercurial's normal <command>hgmerge</command> " dongsheng@627: "program to do the merge, because it would drop my nice automated example-" dongsheng@627: "running tool into a graphical user interface. Instead, I'll set " dongsheng@627: "<envar>HGMERGE</envar> to tell Mercurial to use the non-interactive " dongsheng@627: "<command>merge</command> command. This is bundled with many Unix-like " dongsheng@627: "systems. If you're following this example on your computer, don't bother " dongsheng@627: "setting <envar>HGMERGE</envar>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:308 dongsheng@627: msgid "<emphasis role=\"bold\">XXX FIX THIS EXAMPLE.</emphasis>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:313 dongsheng@627: msgid "" dongsheng@627: "Because <command>merge</command> can't resolve the conflicting changes, it " dongsheng@627: "leaves <emphasis>merge markers</emphasis> inside the file that has conflicts, " dongsheng@627: "indicating which lines have conflicts, and whether they came from our version " dongsheng@627: "of the file or theirs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:319 dongsheng@627: msgid "" dongsheng@627: "Mercurial can tell from the way <command>merge</command> exits that it wasn't " dongsheng@627: "able to merge successfully, so it tells us what commands we'll need to run if " dongsheng@627: "we want to redo the merging operation. This could be useful if, for example, " dongsheng@627: "we were running a graphical merge tool and quit because we were confused or " dongsheng@627: "realised we had made a mistake." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:326 dongsheng@627: msgid "" dongsheng@627: "If automatic or manual merges fail, there's nothing to prevent us from " dongsheng@627: "<quote>fixing up</quote> the affected files ourselves, and committing the " dongsheng@627: "results of our merge:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch03-tour-merge.xml:335 dongsheng@627: msgid "Simplifying the pull-merge-commit sequence" dongsheng@627: msgstr "简化拉-合并-提交程序" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:337 dongsheng@627: msgid "" dongsheng@627: "The process of merging changes as outlined above is straightforward, but " dongsheng@627: "requires running three commands in sequence." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:343 dongsheng@627: msgid "" dongsheng@627: "In the case of the final commit, you also need to enter a commit message, " dongsheng@627: "which is almost always going to be a piece of uninteresting " dongsheng@627: "<quote>boilerplate</quote> text." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:347 dongsheng@627: msgid "" dongsheng@627: "It would be nice to reduce the number of steps needed, if this were " dongsheng@627: "possible. Indeed, Mercurial is distributed with an extension called <literal " dongsheng@627: "role=\"hg-ext\">fetch</literal> that does just this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:352 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides a flexible extension mechanism that lets people extend its " dongsheng@627: "functionality, while keeping the core of Mercurial small and easy to deal " dongsheng@627: "with. Some extensions add new commands that you can use from the command " dongsheng@627: "line, while others work <quote>behind the scenes,</quote> for example adding " dongsheng@627: "capabilities to the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:359 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">fetch</literal> extension adds a new command " dongsheng@627: "called, not surprisingly, <command role=\"hg-cmd\">hg fetch</command>. This " dongsheng@627: "extension acts as a combination of <command role=\"hg-cmd\">hg pull</" dongsheng@627: "command>, <command role=\"hg-cmd\">hg update</command> and <command role=\"hg-" dongsheng@627: "cmd\">hg merge</command>. It begins by pulling changes from another " dongsheng@627: "repository into the current repository. If it finds that the changes added a " dongsheng@627: "new head to the repository, it begins a merge, then commits the result of the " dongsheng@627: "merge with an automatically-generated commit message. If no new heads were " dongsheng@627: "added, it updates the working directory to the new tip changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:372 dongsheng@627: msgid "" dongsheng@627: "Enabling the <literal role=\"hg-ext\">fetch</literal> extension is easy. " dongsheng@627: "Edit your <filename role=\"special\">.hgrc</filename>, and either go to the " dongsheng@627: "<literal role=\"rc-extensions\">extensions</literal> section or create an " dongsheng@627: "<literal role=\"rc-extensions\">extensions</literal> section. Then add a line " dongsheng@627: "that simply reads <quote><literal>fetch </literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch03-tour-merge.xml:382 dongsheng@627: msgid "" dongsheng@627: "(Normally, on the right-hand side of the <quote><literal>=</literal></quote> " dongsheng@627: "would appear the location of the extension, but since the <literal role=\"hg-" dongsheng@627: "ext\">fetch</literal> extension is in the standard distribution, Mercurial " dongsheng@627: "knows where to search for it.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch04-concepts.xml:5 dongsheng@627: msgid "Behind the scenes" dongsheng@627: msgstr "Mercurial 内幕" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch04-concepts.xml:7 dongsheng@627: msgid "" dongsheng@627: "Unlike many revision control systems, the concepts upon which Mercurial is " dongsheng@627: "built are simple enough that it's easy to understand how the software really " dongsheng@627: "works. Knowing this certainly isn't necessary, but I find it useful to have " dongsheng@627: "a <quote>mental model</quote> of what's going on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch04-concepts.xml:13 dongsheng@627: msgid "" dongsheng@627: "This understanding gives me confidence that Mercurial has been carefully " dongsheng@627: "designed to be both <emphasis>safe</emphasis> and <emphasis>efficient</" dongsheng@627: "emphasis>. And just as importantly, if it's easy for me to retain a good " dongsheng@627: "idea of what the software is doing when I perform a revision control task, " dongsheng@627: "I'm less likely to be surprised by its behaviour." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch04-concepts.xml:20 dongsheng@627: msgid "" dongsheng@627: "In this chapter, we'll initially cover the core concepts behind Mercurial's " dongsheng@627: "design, then continue to discuss some of the interesting details of its " dongsheng@627: "implementation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:25 dongsheng@627: msgid "Mercurial's historical record" dongsheng@627: msgstr "Mercurial 的历史记录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:28 dongsheng@627: msgid "Tracking the history of a single file" dongsheng@627: msgstr "跟踪单一文件的历史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:30 dongsheng@627: msgid "" dongsheng@627: "When Mercurial tracks modifications to a file, it stores the history of that " dongsheng@627: "file in a metadata object called a <emphasis>filelog</emphasis>. Each entry " dongsheng@627: "in the filelog contains enough information to reconstruct one revision of the " dongsheng@627: "file that is being tracked. Filelogs are stored as files in the <filename " dongsheng@627: "role=\"special\" class=\"directory\">.hg/store/data</filename> directory. A " dongsheng@627: "filelog contains two kinds of information: revision data, and an index to " dongsheng@627: "help Mercurial to find a revision efficiently." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:41 dongsheng@627: msgid "" dongsheng@627: "A file that is large, or has a lot of history, has its filelog stored in " dongsheng@627: "separate data (<quote><literal>.d</literal></quote> suffix) and index " dongsheng@627: "(<quote><literal>.i</literal></quote> suffix) files. For small files without " dongsheng@627: "much history, the revision data and index are combined in a single " dongsheng@627: "<quote><literal>.i</literal></quote> file. The correspondence between a file " dongsheng@627: "in the working directory and the filelog that tracks its history in the " dongsheng@627: "repository is illustrated in figure <xref linkend=\"fig.concepts.filelog\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:53 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/filelog.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:56 dongsheng@627: msgid "" dongsheng@627: "Relationships between files in working directory and filelogs in repository" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:63 dongsheng@627: msgid "Managing tracked files" dongsheng@627: msgstr "管理跟踪的文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:65 dongsheng@627: msgid "" dongsheng@627: "Mercurial uses a structure called a <emphasis>manifest</emphasis> to collect " dongsheng@627: "together information about the files that it tracks. Each entry in the " dongsheng@627: "manifest contains information about the files present in a single changeset. " dongsheng@627: "An entry records which files are present in the changeset, the revision of " dongsheng@627: "each file, and a few other pieces of file metadata." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:75 dongsheng@627: msgid "Recording changeset information" dongsheng@627: msgstr "记录修改集信息" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:77 dongsheng@627: msgid "" dongsheng@627: "The <emphasis>changelog</emphasis> contains information about each " dongsheng@627: "changeset. Each revision records who committed a change, the changeset " dongsheng@627: "comment, other pieces of changeset-related information, and the revision of " dongsheng@627: "the manifest to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:85 dongsheng@627: msgid "Relationships between revisions" dongsheng@627: msgstr "版本之间的关系" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:87 dongsheng@627: msgid "" dongsheng@627: "Within a changelog, a manifest, or a filelog, each revision stores a pointer " dongsheng@627: "to its immediate parent (or to its two parents, if it's a merge revision). " dongsheng@627: "As I mentioned above, there are also relationships between revisions " dongsheng@627: "<emphasis>across</emphasis> these structures, and they are hierarchical in " dongsheng@627: "nature." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:94 dongsheng@627: msgid "" dongsheng@627: "For every changeset in a repository, there is exactly one revision stored in " dongsheng@627: "the changelog. Each revision of the changelog contains a pointer to a single " dongsheng@627: "revision of the manifest. A revision of the manifest stores a pointer to a " dongsheng@627: "single revision of each filelog tracked when that changeset was created. " dongsheng@627: "These relationships are illustrated in figure <xref linkend=\"fig.concepts." dongsheng@627: "metadata\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:103 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/metadata.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:105 dongsheng@627: msgid "Metadata relationships" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:110 dongsheng@627: msgid "" dongsheng@627: "As the illustration shows, there is <emphasis>not</emphasis> a <quote>one to " dongsheng@627: "one</quote> relationship between revisions in the changelog, manifest, or " dongsheng@627: "filelog. If the manifest hasn't changed between two changesets, the changelog " dongsheng@627: "entries for those changesets will point to the same revision of the " dongsheng@627: "manifest. If a file that Mercurial tracks hasn't changed between two " dongsheng@627: "changesets, the entry for that file in the two revisions of the manifest will " dongsheng@627: "point to the same revision of its filelog." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:123 dongsheng@627: msgid "Safe, efficient storage" dongsheng@627: msgstr "安全，高效的存储" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:125 dongsheng@627: msgid "" dongsheng@627: "The underpinnings of changelogs, manifests, and filelogs are provided by a " dongsheng@627: "single structure called the <emphasis>revlog</emphasis>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:130 dongsheng@627: msgid "Efficient storage" dongsheng@627: msgstr "高效存储" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:132 dongsheng@627: msgid "" dongsheng@627: "The revlog provides efficient storage of revisions using a <emphasis>delta</" dongsheng@627: "emphasis> mechanism. Instead of storing a complete copy of a file for each " dongsheng@627: "revision, it stores the changes needed to transform an older revision into " dongsheng@627: "the new revision. For many kinds of file data, these deltas are typically a " dongsheng@627: "fraction of a percent of the size of a full copy of a file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:140 dongsheng@627: msgid "" dongsheng@627: "Some obsolete revision control systems can only work with deltas of text " dongsheng@627: "files. They must either store binary files as complete snapshots or encoded " dongsheng@627: "into a text representation, both of which are wasteful approaches. Mercurial " dongsheng@627: "can efficiently handle deltas of files with arbitrary binary contents; it " dongsheng@627: "doesn't need to treat text as special." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:149 dongsheng@627: msgid "Safe operation" dongsheng@627: msgstr "安全操作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:151 dongsheng@627: msgid "" dongsheng@627: "Mercurial only ever <emphasis>appends</emphasis> data to the end of a revlog " dongsheng@627: "file. It never modifies a section of a file after it has written it. This is " dongsheng@627: "both more robust and efficient than schemes that need to modify or rewrite " dongsheng@627: "data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:157 dongsheng@627: msgid "" dongsheng@627: "In addition, Mercurial treats every write as part of a <emphasis>transaction</" dongsheng@627: "emphasis> that can span a number of files. A transaction is " dongsheng@627: "<emphasis>atomic</emphasis>: either the entire transaction succeeds and its " dongsheng@627: "effects are all visible to readers in one go, or the whole thing is undone. " dongsheng@627: "This guarantee of atomicity means that if you're running two copies of " dongsheng@627: "Mercurial, where one is reading data and one is writing it, the reader will " dongsheng@627: "never see a partially written result that might confuse it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:167 dongsheng@627: msgid "" dongsheng@627: "The fact that Mercurial only appends to files makes it easier to provide this " dongsheng@627: "transactional guarantee. The easier it is to do stuff like this, the more " dongsheng@627: "confident you should be that it's done correctly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:174 dongsheng@627: msgid "Fast retrieval" dongsheng@627: msgstr "快速检索" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:176 dongsheng@627: msgid "" dongsheng@627: "Mercurial cleverly avoids a pitfall common to all earlier revision control " dongsheng@627: "systems: the problem of <emphasis>inefficient retrieval</emphasis>. Most " dongsheng@627: "revision control systems store the contents of a revision as an incremental " dongsheng@627: "series of modifications against a <quote>snapshot</quote>. To reconstruct a " dongsheng@627: "specific revision, you must first read the snapshot, and then every one of " dongsheng@627: "the revisions between the snapshot and your target revision. The more " dongsheng@627: "history that a file accumulates, the more revisions you must read, hence the " dongsheng@627: "longer it takes to reconstruct a particular revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:188 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/snapshot.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:190 dongsheng@627: msgid "Snapshot of a revlog, with incremental deltas" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:195 dongsheng@627: msgid "" dongsheng@627: "The innovation that Mercurial applies to this problem is simple but " dongsheng@627: "effective. Once the cumulative amount of delta information stored since the " dongsheng@627: "last snapshot exceeds a fixed threshold, it stores a new snapshot " dongsheng@627: "(compressed, of course), instead of another delta. This makes it possible to " dongsheng@627: "reconstruct <emphasis>any</emphasis> revision of a file quickly. This " dongsheng@627: "approach works so well that it has since been copied by several other " dongsheng@627: "revision control systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:204 dongsheng@627: msgid "" dongsheng@627: "Figure <xref linkend=\"fig.concepts.snapshot\"/> illustrates the idea. In an " dongsheng@627: "entry in a revlog's index file, Mercurial stores the range of entries from " dongsheng@627: "the data file that it must read to reconstruct a particular revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch04-concepts.xml:210 dongsheng@627: msgid "Aside: the influence of video compression" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:212 dongsheng@627: msgid "" dongsheng@627: "If you're familiar with video compression or have ever watched a TV feed " dongsheng@627: "through a digital cable or satellite service, you may know that most video " dongsheng@627: "compression schemes store each frame of video as a delta against its " dongsheng@627: "predecessor frame. In addition, these schemes use <quote>lossy</quote> " dongsheng@627: "compression techniques to increase the compression ratio, so visual errors " dongsheng@627: "accumulate over the course of a number of inter-frame deltas." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:221 dongsheng@627: msgid "" dongsheng@627: "Because it's possible for a video stream to <quote>drop out</quote> " dongsheng@627: "occasionally due to signal glitches, and to limit the accumulation of " dongsheng@627: "artefacts introduced by the lossy compression process, video encoders " dongsheng@627: "periodically insert a complete frame (called a <quote>key frame</quote>) into " dongsheng@627: "the video stream; the next delta is generated against that frame. This means " dongsheng@627: "that if the video signal gets interrupted, it will resume once the next key " dongsheng@627: "frame is received. Also, the accumulation of encoding errors restarts anew " dongsheng@627: "with each key frame." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:235 dongsheng@627: msgid "Identification and strong integrity" dongsheng@627: msgstr "鉴别和强完整性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:237 dongsheng@627: msgid "" dongsheng@627: "Along with delta or snapshot information, a revlog entry contains a " dongsheng@627: "cryptographic hash of the data that it represents. This makes it difficult " dongsheng@627: "to forge the contents of a revision, and easy to detect accidental corruption." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:242 dongsheng@627: msgid "" dongsheng@627: "Hashes provide more than a mere check against corruption; they are used as " dongsheng@627: "the identifiers for revisions. The changeset identification hashes that you " dongsheng@627: "see as an end user are from revisions of the changelog. Although filelogs " dongsheng@627: "and the manifest also use hashes, Mercurial only uses these behind the scenes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:249 dongsheng@627: msgid "" dongsheng@627: "Mercurial verifies that hashes are correct when it retrieves file revisions " dongsheng@627: "and when it pulls changes from another repository. If it encounters an " dongsheng@627: "integrity problem, it will complain and stop whatever it's doing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:254 dongsheng@627: msgid "" dongsheng@627: "In addition to the effect it has on retrieval efficiency, Mercurial's use of " dongsheng@627: "periodic snapshots makes it more robust against partial data corruption. If " dongsheng@627: "a revlog becomes partly corrupted due to a hardware error or system bug, it's " dongsheng@627: "often possible to reconstruct some or most revisions from the uncorrupted " dongsheng@627: "sections of the revlog, both before and after the corrupted section. This " dongsheng@627: "would not be possible with a delta-only storage model." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:266 dongsheng@627: msgid "Revision history, branching, and merging" dongsheng@627: msgstr "修订历史，分支与合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:268 dongsheng@627: msgid "" dongsheng@627: "Every entry in a Mercurial revlog knows the identity of its immediate " dongsheng@627: "ancestor revision, usually referred to as its <emphasis>parent</emphasis>. " dongsheng@627: "In fact, a revision contains room for not one parent, but two. Mercurial " dongsheng@627: "uses a special hash, called the <quote>null ID</quote>, to represent the idea " dongsheng@627: "<quote>there is no parent here</quote>. This hash is simply a string of " dongsheng@627: "zeroes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:276 dongsheng@627: msgid "" dongsheng@627: "In figure <xref linkend=\"fig.concepts.revlog\"/>, you can see an example of " dongsheng@627: "the conceptual structure of a revlog. Filelogs, manifests, and changelogs " dongsheng@627: "all have this same structure; they differ only in the kind of data stored in " dongsheng@627: "each delta or snapshot." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:282 dongsheng@627: msgid "" dongsheng@627: "The first revision in a revlog (at the bottom of the image) has the null ID " dongsheng@627: "in both of its parent slots. For a <quote>normal</quote> revision, its first " dongsheng@627: "parent slot contains the ID of its parent revision, and its second contains " dongsheng@627: "the null ID, indicating that the revision has only one real parent. Any two " dongsheng@627: "revisions that have the same parent ID are branches. A revision that " dongsheng@627: "represents a merge between branches has two normal revision IDs in its parent " dongsheng@627: "slots." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:292 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/revlog.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:299 dongsheng@627: msgid "The working directory" dongsheng@627: msgstr "工作目录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:301 dongsheng@627: msgid "" dongsheng@627: "In the working directory, Mercurial stores a snapshot of the files from the " dongsheng@627: "repository as of a particular changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:304 dongsheng@627: msgid "" dongsheng@627: "The working directory <quote>knows</quote> which changeset it contains. When " dongsheng@627: "you update the working directory to contain a particular changeset, Mercurial " dongsheng@627: "looks up the appropriate revision of the manifest to find out which files it " dongsheng@627: "was tracking at the time that changeset was committed, and which revision of " dongsheng@627: "each file was then current. It then recreates a copy of each of those files, " dongsheng@627: "with the same contents it had when the changeset was committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:313 dongsheng@627: msgid "" dongsheng@627: "The <emphasis>dirstate</emphasis> contains Mercurial's knowledge of the " dongsheng@627: "working directory. This details which changeset the working directory is " dongsheng@627: "updated to, and all of the files that Mercurial is tracking in the working " dongsheng@627: "directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:319 dongsheng@627: msgid "" dongsheng@627: "Just as a revision of a revlog has room for two parents, so that it can " dongsheng@627: "represent either a normal revision (with one parent) or a merge of two " dongsheng@627: "earlier revisions, the dirstate has slots for two parents. When you use the " dongsheng@627: "<command role=\"hg-cmd\">hg update</command> command, the changeset that you " dongsheng@627: "update to is stored in the <quote>first parent</quote> slot, and the null ID " dongsheng@627: "in the second. When you <command role=\"hg-cmd\">hg merge</command> with " dongsheng@627: "another changeset, the first parent remains unchanged, and the second parent " dongsheng@627: "is filled in with the changeset you're merging with. The <command role=\"hg-" dongsheng@627: "cmd\">hg parents</command> command tells you what the parents of the dirstate " dongsheng@627: "are." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:333 dongsheng@627: msgid "What happens when you commit" dongsheng@627: msgstr "当你提交时发生的事情" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:335 dongsheng@627: msgid "" dongsheng@627: "The dirstate stores parent information for more than just book-keeping " dongsheng@627: "purposes. Mercurial uses the parents of the dirstate as <emphasis>the " dongsheng@627: "parents of a new changeset</emphasis> when you perform a commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:341 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/wdir.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:343 dongsheng@627: msgid "The working directory can have two parents" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:348 dongsheng@627: msgid "" dongsheng@627: "Figure <xref linkend=\"fig.concepts.wdir\"/> shows the normal state of the " dongsheng@627: "working directory, where it has a single changeset as parent. That changeset " dongsheng@627: "is the <emphasis>tip</emphasis>, the newest changeset in the repository that " dongsheng@627: "has no children." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:355 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/wdir-after-commit.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:357 dongsheng@627: msgid "The working directory gains new parents after a commit" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:362 dongsheng@627: msgid "" dongsheng@627: "It's useful to think of the working directory as <quote>the changeset I'm " dongsheng@627: "about to commit</quote>. Any files that you tell Mercurial that you've " dongsheng@627: "added, removed, renamed, or copied will be reflected in that changeset, as " dongsheng@627: "will modifications to any files that Mercurial is already tracking; the new " dongsheng@627: "changeset will have the parents of the working directory as its parents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:370 dongsheng@627: msgid "" dongsheng@627: "After a commit, Mercurial will update the parents of the working directory, " dongsheng@627: "so that the first parent is the ID of the new changeset, and the second is " dongsheng@627: "the null ID. This is shown in figure <xref linkend=\"fig.concepts.wdir-after-" dongsheng@627: "commit\"/>. Mercurial doesn't touch any of the files in the working " dongsheng@627: "directory when you commit; it just modifies the dirstate to note its new " dongsheng@627: "parents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:381 dongsheng@627: msgid "Creating a new head" dongsheng@627: msgstr "创建新顶点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:383 dongsheng@627: msgid "" dongsheng@627: "It's perfectly normal to update the working directory to a changeset other " dongsheng@627: "than the current tip. For example, you might want to know what your project " dongsheng@627: "looked like last Tuesday, or you could be looking through changesets to see " dongsheng@627: "which one introduced a bug. In cases like this, the natural thing to do is " dongsheng@627: "update the working directory to the changeset you're interested in, and then " dongsheng@627: "examine the files in the working directory directly to see their contents as " dongsheng@627: "they were when you committed that changeset. The effect of this is shown in " dongsheng@627: "figure <xref linkend=\"fig.concepts.wdir-pre-branch\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:395 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/wdir-pre-branch.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:397 dongsheng@627: msgid "The working directory, updated to an older changeset" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:402 dongsheng@627: msgid "" dongsheng@627: "Having updated the working directory to an older changeset, what happens if " dongsheng@627: "you make some changes, and then commit? Mercurial behaves in the same way as " dongsheng@627: "I outlined above. The parents of the working directory become the parents of " dongsheng@627: "the new changeset. This new changeset has no children, so it becomes the new " dongsheng@627: "tip. And the repository now contains two changesets that have no children; " dongsheng@627: "we call these <emphasis>heads</emphasis>. You can see the structure that " dongsheng@627: "this creates in figure <xref linkend=\"fig.concepts.wdir-branch\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:414 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/wdir-branch.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:416 dongsheng@627: msgid "After a commit made while synced to an older changeset" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch04-concepts.xml:422 dongsheng@627: msgid "" dongsheng@627: "If you're new to Mercurial, you should keep in mind a common <quote>error</" dongsheng@627: "quote>, which is to use the <command role=\"hg-cmd\">hg pull</command> " dongsheng@627: "command without any options. By default, the <command role=\"hg-cmd\">hg " dongsheng@627: "pull</command> command <emphasis>does not</emphasis> update the working " dongsheng@627: "directory, so you'll bring new changesets into your repository, but the " dongsheng@627: "working directory will stay synced at the same changeset as before the pull. " dongsheng@627: "If you make some changes and commit afterwards, you'll thus create a new " dongsheng@627: "head, because your working directory isn't synced to whatever the current tip " dongsheng@627: "is." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch04-concepts.xml:434 dongsheng@627: msgid "" dongsheng@627: "I put the word <quote>error</quote> in quotes because all that you need to do " dongsheng@627: "to rectify this situation is <command role=\"hg-cmd\">hg merge</command>, " dongsheng@627: "then <command role=\"hg-cmd\">hg commit</command>. In other words, this " dongsheng@627: "almost never has negative consequences; it just surprises people. I'll " dongsheng@627: "discuss other ways to avoid this behaviour, and why Mercurial behaves in this " dongsheng@627: "initially surprising way, later on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:446 dongsheng@627: msgid "Merging heads" dongsheng@627: msgstr "合并顶点" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:448 dongsheng@627: msgid "" dongsheng@627: "When you run the <command role=\"hg-cmd\">hg merge</command> command, " dongsheng@627: "Mercurial leaves the first parent of the working directory unchanged, and " dongsheng@627: "sets the second parent to the changeset you're merging with, as shown in " dongsheng@627: "figure <xref linkend=\"fig.concepts.wdir-merge\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch04-concepts.xml:455 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/wdir-merge.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch04-concepts.xml:457 dongsheng@627: msgid "Merging two heads" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:461 dongsheng@627: msgid "" dongsheng@627: "Mercurial also has to modify the working directory, to merge the files " dongsheng@627: "managed in the two changesets. Simplified a little, the merging process goes " dongsheng@627: "like this, for every file in the manifests of both changesets." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:466 dongsheng@627: msgid "If neither changeset has modified a file, do nothing with that file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:469 dongsheng@627: msgid "" dongsheng@627: "If one changeset has modified a file, and the other hasn't, create the " dongsheng@627: "modified copy of the file in the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:473 dongsheng@627: msgid "" dongsheng@627: "If one changeset has removed a file, and the other hasn't (or has also " dongsheng@627: "deleted it), delete the file from the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:477 dongsheng@627: msgid "" dongsheng@627: "If one changeset has removed a file, but the other has modified the file, ask " dongsheng@627: "the user what to do: keep the modified file, or remove it?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:481 dongsheng@627: msgid "" dongsheng@627: "If both changesets have modified a file, invoke an external merge program to " dongsheng@627: "choose the new contents for the merged file. This may require input from the " dongsheng@627: "user." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch04-concepts.xml:486 dongsheng@627: msgid "" dongsheng@627: "If one changeset has modified a file, and the other has renamed or copied the " dongsheng@627: "file, make sure that the changes follow the new name of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:490 dongsheng@627: msgid "" dongsheng@627: "There are more details&emdash;merging has plenty of corner cases&emdash;but " dongsheng@627: "these are the most common choices that are involved in a merge. As you can " dongsheng@627: "see, most cases are completely automatic, and indeed most merges finish " dongsheng@627: "automatically, without requiring your input to resolve any conflicts." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:497 dongsheng@627: msgid "" dongsheng@627: "When you're thinking about what happens when you commit after a merge, once " dongsheng@627: "again the working directory is <quote>the changeset I'm about to commit</" dongsheng@627: "quote>. After the <command role=\"hg-cmd\">hg merge</command> command " dongsheng@627: "completes, the working directory has two parents; these will become the " dongsheng@627: "parents of the new changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:504 dongsheng@627: msgid "" dongsheng@627: "Mercurial lets you perform multiple merges, but you must commit the results " dongsheng@627: "of each individual merge as you go. This is necessary because Mercurial only " dongsheng@627: "tracks two parents for both revisions and the working directory. While it " dongsheng@627: "would be technically possible to merge multiple changesets at once, the " dongsheng@627: "prospect of user confusion and making a terrible mess of a merge immediately " dongsheng@627: "becomes overwhelming." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch04-concepts.xml:515 dongsheng@627: msgid "Other interesting design features" dongsheng@627: msgstr "其它有趣的设计特性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch04-concepts.xml:517 dongsheng@627: msgid "" dongsheng@627: "In the sections above, I've tried to highlight some of the most important " dongsheng@627: "aspects of Mercurial's design, to illustrate that it pays careful attention " dongsheng@627: "to reliability and performance. However, the attention to detail doesn't " dongsheng@627: "stop there. There are a number of other aspects of Mercurial's construction " dongsheng@627: "that I personally find interesting. I'll detail a few of them here, separate " dongsheng@627: "from the <quote>big ticket</quote> items above, so that if you're interested, " dongsheng@627: "you can gain a better idea of the amount of thinking that goes into a well-" dongsheng@627: "designed system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:528 dongsheng@627: msgid "Clever compression" dongsheng@627: msgstr "智能压缩" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:530 dongsheng@627: msgid "" dongsheng@627: "When appropriate, Mercurial will store both snapshots and deltas in " dongsheng@627: "compressed form. It does this by always <emphasis>trying to</emphasis> " dongsheng@627: "compress a snapshot or delta, but only storing the compressed version if it's " dongsheng@627: "smaller than the uncompressed version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:536 dongsheng@627: msgid "" dongsheng@627: "This means that Mercurial does <quote>the right thing</quote> when storing a " dongsheng@627: "file whose native form is compressed, such as a <literal>zip</literal> " dongsheng@627: "archive or a JPEG image. When these types of files are compressed a second " dongsheng@627: "time, the resulting file is usually bigger than the once-compressed form, and " dongsheng@627: "so Mercurial will store the plain <literal>zip</literal> or JPEG." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:544 dongsheng@627: msgid "" dongsheng@627: "Deltas between revisions of a compressed file are usually larger than " dongsheng@627: "snapshots of the file, and Mercurial again does <quote>the right thing</" dongsheng@627: "quote> in these cases. It finds that such a delta exceeds the threshold at " dongsheng@627: "which it should store a complete snapshot of the file, so it stores the " dongsheng@627: "snapshot, again saving space compared to a naive delta-only approach." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch04-concepts.xml:553 dongsheng@627: msgid "Network recompression" dongsheng@627: msgstr "网络重新压缩" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:555 dongsheng@627: msgid "" dongsheng@627: "When storing revisions on disk, Mercurial uses the <quote>deflate</quote> " dongsheng@627: "compression algorithm (the same one used by the popular <literal>zip</" dongsheng@627: "literal> archive format), which balances good speed with a respectable " dongsheng@627: "compression ratio. However, when transmitting revision data over a network " dongsheng@627: "connection, Mercurial uncompresses the compressed revision data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:563 dongsheng@627: msgid "" dongsheng@627: "If the connection is over HTTP, Mercurial recompresses the entire stream of " dongsheng@627: "data using a compression algorithm that gives a better compression ratio (the " dongsheng@627: "Burrows-Wheeler algorithm from the widely used <literal>bzip2</literal> " dongsheng@627: "compression package). This combination of algorithm and compression of the " dongsheng@627: "entire stream (instead of a revision at a time) substantially reduces the " dongsheng@627: "number of bytes to be transferred, yielding better network performance over " dongsheng@627: "almost all kinds of network." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:573 dongsheng@627: msgid "" dongsheng@627: "(If the connection is over <command>ssh</command>, Mercurial " dongsheng@627: "<emphasis>doesn't</emphasis> recompress the stream, because <command>ssh</" dongsheng@627: "command> can already do this itself.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:581 dongsheng@627: msgid "Read/write ordering and atomicity" dongsheng@627: msgstr "读写顺序与原子性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:583 dongsheng@627: msgid "" dongsheng@627: "Appending to files isn't the whole story when it comes to guaranteeing that a " dongsheng@627: "reader won't see a partial write. If you recall figure <xref linkend=\"fig." dongsheng@627: "concepts.metadata\"/>, revisions in the changelog point to revisions in the " dongsheng@627: "manifest, and revisions in the manifest point to revisions in filelogs. This " dongsheng@627: "hierarchy is deliberate." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:591 dongsheng@627: msgid "" dongsheng@627: "A writer starts a transaction by writing filelog and manifest data, and " dongsheng@627: "doesn't write any changelog data until those are finished. A reader starts " dongsheng@627: "by reading changelog data, then manifest data, followed by filelog data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:596 dongsheng@627: msgid "" dongsheng@627: "Since the writer has always finished writing filelog and manifest data before " dongsheng@627: "it writes to the changelog, a reader will never read a pointer to a partially " dongsheng@627: "written manifest revision from the changelog, and it will never read a " dongsheng@627: "pointer to a partially written filelog revision from the manifest." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:604 dongsheng@627: msgid "Concurrent access" dongsheng@627: msgstr "并发访问" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:606 dongsheng@627: msgid "" dongsheng@627: "The read/write ordering and atomicity guarantees mean that Mercurial never " dongsheng@627: "needs to <emphasis>lock</emphasis> a repository when it's reading data, even " dongsheng@627: "if the repository is being written to while the read is occurring. This has a " dongsheng@627: "big effect on scalability; you can have an arbitrary number of Mercurial " dongsheng@627: "processes safely reading data from a repository safely all at once, no matter " dongsheng@627: "whether it's being written to or not." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:615 dongsheng@627: msgid "" dongsheng@627: "The lockless nature of reading means that if you're sharing a repository on a " dongsheng@627: "multi-user system, you don't need to grant other local users permission to " dongsheng@627: "<emphasis>write</emphasis> to your repository in order for them to be able to " dongsheng@627: "clone it or pull changes from it; they only need <emphasis>read</emphasis> " dongsheng@627: "permission. (This is <emphasis>not</emphasis> a common feature among " dongsheng@627: "revision control systems, so don't take it for granted! Most require readers " dongsheng@627: "to be able to lock a repository to access it safely, and this requires write " dongsheng@627: "permission on at least one directory, which of course makes for all kinds of " dongsheng@627: "nasty and annoying security and administrative problems.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:628 dongsheng@627: msgid "" dongsheng@627: "Mercurial uses locks to ensure that only one process can write to a " dongsheng@627: "repository at a time (the locking mechanism is safe even over filesystems " dongsheng@627: "that are notoriously hostile to locking, such as NFS). If a repository is " dongsheng@627: "locked, a writer will wait for a while to retry if the repository becomes " dongsheng@627: "unlocked, but if the repository remains locked for too long, the process " dongsheng@627: "attempting to write will time out after a while. This means that your daily " dongsheng@627: "automated scripts won't get stuck forever and pile up if a system crashes " dongsheng@627: "unnoticed, for example. (Yes, the timeout is configurable, from zero to " dongsheng@627: "infinity.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch04-concepts.xml:640 dongsheng@627: msgid "Safe dirstate access" dongsheng@627: msgstr "安全的目录状态访问" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch04-concepts.xml:642 dongsheng@627: msgid "" dongsheng@627: "As with revision data, Mercurial doesn't take a lock to read the dirstate " dongsheng@627: "file; it does acquire a lock to write it. To avoid the possibility of " dongsheng@627: "reading a partially written copy of the dirstate file, Mercurial writes to a " dongsheng@627: "file with a unique name in the same directory as the dirstate file, then " dongsheng@627: "renames the temporary file atomically to <filename>dirstate</filename>. The " dongsheng@627: "file named <filename>dirstate</filename> is thus guaranteed to be complete, " dongsheng@627: "not partially written." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:655 dongsheng@627: msgid "Avoiding seeks" dongsheng@627: msgstr "避免查找" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:657 dongsheng@627: msgid "" dongsheng@627: "Critical to Mercurial's performance is the avoidance of seeks of the disk " dongsheng@627: "head, since any seek is far more expensive than even a comparatively large " dongsheng@627: "read operation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:661 dongsheng@627: msgid "" dongsheng@627: "This is why, for example, the dirstate is stored in a single file. If there " dongsheng@627: "were a dirstate file per directory that Mercurial tracked, the disk would " dongsheng@627: "seek once per directory. Instead, Mercurial reads the entire single dirstate " dongsheng@627: "file in one step." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:667 dongsheng@627: msgid "" dongsheng@627: "Mercurial also uses a <quote>copy on write</quote> scheme when cloning a " dongsheng@627: "repository on local storage. Instead of copying every revlog file from the " dongsheng@627: "old repository into the new repository, it makes a <quote>hard link</quote>, " dongsheng@627: "which is a shorthand way to say <quote>these two names point to the same " dongsheng@627: "file</quote>. When Mercurial is about to write to one of a revlog's files, " dongsheng@627: "it checks to see if the number of names pointing at the file is greater than " dongsheng@627: "one. If it is, more than one repository is using the file, so Mercurial " dongsheng@627: "makes a new copy of the file that is private to this repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:678 dongsheng@627: msgid "" dongsheng@627: "A few revision control developers have pointed out that this idea of making a " dongsheng@627: "complete private copy of a file is not very efficient in its use of storage. " dongsheng@627: "While this is true, storage is cheap, and this method gives the highest " dongsheng@627: "performance while deferring most book-keeping to the operating system. An " dongsheng@627: "alternative scheme would most likely reduce performance and increase the " dongsheng@627: "complexity of the software, each of which is much more important to the " dongsheng@627: "<quote>feel</quote> of day-to-day use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch04-concepts.xml:690 dongsheng@627: msgid "Other contents of the dirstate" dongsheng@627: msgstr "目录状态的其它内容" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:692 dongsheng@627: msgid "" dongsheng@627: "Because Mercurial doesn't force you to tell it when you're modifying a file, " dongsheng@627: "it uses the dirstate to store some extra information so it can determine " dongsheng@627: "efficiently whether you have modified a file. For each file in the working " dongsheng@627: "directory, it stores the time that it last modified the file itself, and the " dongsheng@627: "size of the file at that time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:699 dongsheng@627: msgid "" dongsheng@627: "When you explicitly <command role=\"hg-cmd\">hg add</command>, <command role=" dongsheng@627: "\"hg-cmd\">hg remove</command>, <command role=\"hg-cmd\">hg rename</command> " dongsheng@627: "or <command role=\"hg-cmd\">hg copy</command> files, Mercurial updates the " dongsheng@627: "dirstate so that it knows what to do with those files when you commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch04-concepts.xml:706 dongsheng@627: msgid "" dongsheng@627: "When Mercurial is checking the states of files in the working directory, it " dongsheng@627: "first checks a file's modification time. If that has not changed, the file " dongsheng@627: "must not have been modified. If the file's size has changed, the file must " dongsheng@627: "have been modified. If the modification time has changed, but the size has " dongsheng@627: "not, only then does Mercurial need to read the actual contents of the file to " dongsheng@627: "see if they've changed. Storing these few extra pieces of information " dongsheng@627: "dramatically reduces the amount of data that Mercurial needs to read, which " dongsheng@627: "yields large performance improvements compared to other revision control " dongsheng@627: "systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch05-daily.xml:5 dongsheng@627: msgid "Mercurial in daily use" dongsheng@627: msgstr "Mercurial 的日常使用" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:8 dongsheng@627: msgid "Telling Mercurial which files to track" dongsheng@627: msgstr "告诉 Mercurial 要跟踪哪些文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:10 dongsheng@627: msgid "" dongsheng@627: "Mercurial does not work with files in your repository unless you tell it to " dongsheng@627: "manage them. The <command role=\"hg-cmd\">hg status</command> command will " dongsheng@627: "tell you which files Mercurial doesn't know about; it uses a <quote><literal>?" dongsheng@627: "</literal></quote> to display such files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:17 dongsheng@627: msgid "" dongsheng@627: "To tell Mercurial to track a file, use the <command role=\"hg-cmd\">hg add</" dongsheng@627: "command> command. Once you have added a file, the entry in the output of " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> for that file changes from " dongsheng@627: "<quote><literal>?</literal></quote> to <quote><literal>A</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:26 dongsheng@627: msgid "" dongsheng@627: "After you run a <command role=\"hg-cmd\">hg commit</command>, the files that " dongsheng@627: "you added before the commit will no longer be listed in the output of " dongsheng@627: "<command role=\"hg-cmd\">hg status</command>. The reason for this is that " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> only tells you about " dongsheng@627: "<quote>interesting</quote> files&emdash;those that you have modified or told " dongsheng@627: "Mercurial to do something with&emdash;by default. If you have a repository " dongsheng@627: "that contains thousands of files, you will rarely want to know about files " dongsheng@627: "that Mercurial is tracking, but that have not changed. (You can still get " dongsheng@627: "this information; we'll return to this later.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:38 dongsheng@627: msgid "" dongsheng@627: "Once you add a file, Mercurial doesn't do anything with it immediately. " dongsheng@627: "Instead, it will take a snapshot of the file's state the next time you " dongsheng@627: "perform a commit. It will then continue to track the changes you make to the " dongsheng@627: "file every time you commit, until you remove the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:45 dongsheng@627: msgid "Explicit versus implicit file naming" dongsheng@627: msgstr "明确与隐含文件命名" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:47 dongsheng@627: msgid "" dongsheng@627: "A useful behaviour that Mercurial has is that if you pass the name of a " dongsheng@627: "directory to a command, every Mercurial command will treat this as <quote>I " dongsheng@627: "want to operate on every file in this directory and its subdirectories</" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:54 dongsheng@627: msgid "" dongsheng@627: "Notice in this example that Mercurial printed the names of the files it " dongsheng@627: "added, whereas it didn't do so when we added the file named <filename>a</" dongsheng@627: "filename> in the earlier example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:59 dongsheng@627: msgid "" dongsheng@627: "What's going on is that in the former case, we explicitly named the file to " dongsheng@627: "add on the command line, so the assumption that Mercurial makes in such cases " dongsheng@627: "is that you know what you were doing, and it doesn't print any output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:64 dongsheng@627: msgid "" dongsheng@627: "However, when we <emphasis>imply</emphasis> the names of files by giving the " dongsheng@627: "name of a directory, Mercurial takes the extra step of printing the name of " dongsheng@627: "each file that it does something with. This makes it more clear what is " dongsheng@627: "happening, and reduces the likelihood of a silent and nasty surprise. This " dongsheng@627: "behaviour is common to most Mercurial commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:73 dongsheng@627: msgid "Aside: Mercurial tracks files, not directories" dongsheng@627: msgstr "旁白: Mercurial 只跟踪文件，不跟踪目录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:75 dongsheng@627: msgid "" dongsheng@627: "Mercurial does not track directory information. Instead, it tracks the path " dongsheng@627: "to a file. Before creating a file, it first creates any missing directory " dongsheng@627: "components of the path. After it deletes a file, it then deletes any empty " dongsheng@627: "directories that were in the deleted file's path. This sounds like a trivial " dongsheng@627: "distinction, but it has one minor practical consequence: it is not possible " dongsheng@627: "to represent a completely empty directory in Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:84 dongsheng@627: msgid "" dongsheng@627: "Empty directories are rarely useful, and there are unintrusive workarounds " dongsheng@627: "that you can use to achieve an appropriate effect. The developers of " dongsheng@627: "Mercurial thus felt that the complexity that would be required to manage " dongsheng@627: "empty directories was not worth the limited benefit this feature would bring." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:91 dongsheng@627: msgid "" dongsheng@627: "If you need an empty directory in your repository, there are a few ways to " dongsheng@627: "achieve this. One is to create a directory, then <command role=\"hg-cmd\">hg " dongsheng@627: "add</command> a <quote>hidden</quote> file to that directory. On Unix-like " dongsheng@627: "systems, any file name that begins with a period (<quote><literal>.</" dongsheng@627: "literal></quote>) is treated as hidden by most commands and GUI tools. This " dongsheng@627: "approach is illustrated below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:102 dongsheng@627: msgid "" dongsheng@627: "Another way to tackle a need for an empty directory is to simply create one " dongsheng@627: "in your automated build scripts before they will need it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:109 dongsheng@627: msgid "How to stop tracking a file" dongsheng@627: msgstr "如何停止跟踪文件" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:111 dongsheng@627: msgid "" dongsheng@627: "Once you decide that a file no longer belongs in your repository, use the " dongsheng@627: "<command role=\"hg-cmd\">hg remove</command> command; this deletes the file, " dongsheng@627: "and tells Mercurial to stop tracking it. A removed file is represented in " dongsheng@627: "the output of <command role=\"hg-cmd\">hg status</command> with a " dongsheng@627: "<quote><literal>R</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:120 dongsheng@627: msgid "" dongsheng@627: "After you <command role=\"hg-cmd\">hg remove</command> a file, Mercurial will " dongsheng@627: "no longer track changes to that file, even if you recreate a file with the " dongsheng@627: "same name in your working directory. If you do recreate a file with the same " dongsheng@627: "name and want Mercurial to track the new file, simply <command role=\"hg-cmd" dongsheng@627: "\">hg add</command> it. Mercurial will know that the newly added file is not " dongsheng@627: "related to the old file of the same name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:129 dongsheng@627: msgid "Removing a file does not affect its history" dongsheng@627: msgstr "删除文件不影响历史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:131 dongsheng@627: msgid "It is important to understand that removing a file has only two effects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch05-daily.xml:134 dongsheng@627: msgid "It removes the current version of the file from the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch05-daily.xml:137 dongsheng@627: msgid "" dongsheng@627: "It stops Mercurial from tracking changes to the file, from the time of the " dongsheng@627: "next commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:140 dongsheng@627: msgid "" dongsheng@627: "Removing a file <emphasis>does not</emphasis> in any way alter the " dongsheng@627: "<emphasis>history</emphasis> of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:143 dongsheng@627: msgid "" dongsheng@627: "If you update the working directory to a changeset in which a file that you " dongsheng@627: "have removed was still tracked, it will reappear in the working directory, " dongsheng@627: "with the contents it had when you committed that changeset. If you then " dongsheng@627: "update the working directory to a later changeset, in which the file had been " dongsheng@627: "removed, Mercurial will once again remove the file from the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:153 dongsheng@627: msgid "Missing files" dongsheng@627: msgstr "丢失的文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:155 dongsheng@627: msgid "" dongsheng@627: "Mercurial considers a file that you have deleted, but not used <command role=" dongsheng@627: "\"hg-cmd\">hg remove</command> to delete, to be <emphasis>missing</" dongsheng@627: "emphasis>. A missing file is represented with <quote><literal>!</literal></" dongsheng@627: "quote> in the output of <command role=\"hg-cmd\">hg status</command>. " dongsheng@627: "Mercurial commands will not generally do anything with missing files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:165 dongsheng@627: msgid "" dongsheng@627: "If your repository contains a file that <command role=\"hg-cmd\">hg status</" dongsheng@627: "command> reports as missing, and you want the file to stay gone, you can run " dongsheng@627: "<command role=\"hg-cmd\">hg remove <option role=\"hg-opt-remove\">--after</" dongsheng@627: "option></command> at any time later on, to tell Mercurial that you really did " dongsheng@627: "mean to remove the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:175 dongsheng@627: msgid "" dongsheng@627: "On the other hand, if you deleted the missing file by accident, give <command " dongsheng@627: "role=\"hg-cmd\">hg revert</command> the name of the file to recover. It will " dongsheng@627: "reappear, in unmodified form." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:184 dongsheng@627: msgid "Aside: why tell Mercurial explicitly to remove a file?" dongsheng@627: msgstr "旁白: 为什么要明确告诉 Mercurial 删除文件?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:187 dongsheng@627: msgid "" dongsheng@627: "You might wonder why Mercurial requires you to explicitly tell it that you " dongsheng@627: "are deleting a file. Early during the development of Mercurial, it let you " dongsheng@627: "delete a file however you pleased; Mercurial would notice the absence of the " dongsheng@627: "file automatically when you next ran a <command role=\"hg-cmd\">hg commit</" dongsheng@627: "command>, and stop tracking the file. In practice, this made it too easy to " dongsheng@627: "accidentally remove a file without noticing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:198 dongsheng@627: msgid "Useful shorthand&emdash;adding and removing files in one step" dongsheng@627: msgstr "有用的速记&emdash;一个步骤添加和删除文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:201 dongsheng@627: msgid "" dongsheng@627: "Mercurial offers a combination command, <command role=\"hg-cmd\">hg " dongsheng@627: "addremove</command>, that adds untracked files and marks missing files as " dongsheng@627: "removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:207 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg commit</command> command also provides a " dongsheng@627: "<option role=\"hg-opt-commit\">-A</option> option that performs this same add-" dongsheng@627: "and-remove, immediately followed by a commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:217 dongsheng@627: msgid "Copying files" dongsheng@627: msgstr "复制文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:219 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides a <command role=\"hg-cmd\">hg copy</command> command that " dongsheng@627: "lets you make a new copy of a file. When you copy a file using this command, " dongsheng@627: "Mercurial makes a record of the fact that the new file is a copy of the " dongsheng@627: "original file. It treats these copied files specially when you merge your " dongsheng@627: "work with someone else's." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:227 dongsheng@627: msgid "The results of copying during a merge" dongsheng@627: msgstr "合并期间的复制结果" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:229 dongsheng@627: msgid "" dongsheng@627: "What happens during a merge is that changes <quote>follow</quote> a copy. To " dongsheng@627: "best illustrate what this means, let's create an example. We'll start with " dongsheng@627: "the usual tiny repository that contains a single file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:236 dongsheng@627: msgid "" dongsheng@627: "We need to do some work in parallel, so that we'll have something to merge. " dongsheng@627: "So let's clone our repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:242 dongsheng@627: msgid "" dongsheng@627: "Back in our initial repository, let's use the <command role=\"hg-cmd\">hg " dongsheng@627: "copy</command> command to make a copy of the first file we created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:248 dongsheng@627: msgid "" dongsheng@627: "If we look at the output of the <command role=\"hg-cmd\">hg status</command> " dongsheng@627: "command afterwards, the copied file looks just like a normal added file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:254 dongsheng@627: msgid "" dongsheng@627: "But if we pass the <option role=\"hg-opt-status\">-C</option> option to " dongsheng@627: "<command role=\"hg-cmd\">hg status</command>, it prints another line of " dongsheng@627: "output: this is the file that our newly-added file was copied <emphasis>from</" dongsheng@627: "emphasis>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:262 dongsheng@627: msgid "" dongsheng@627: "Now, back in the repository we cloned, let's make a change in parallel. " dongsheng@627: "We'll add a line of content to the original file that we created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:268 dongsheng@627: msgid "" dongsheng@627: "Now we have a modified <filename>file</filename> in this repository. When we " dongsheng@627: "pull the changes from the first repository, and merge the two heads, " dongsheng@627: "Mercurial will propagate the changes that we made locally to <filename>file</" dongsheng@627: "filename> into its copy, <filename>new-file</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:278 dongsheng@627: msgid "Why should changes follow copies?" dongsheng@627: msgstr "为什么复制后需要后续修改?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:280 dongsheng@627: msgid "" dongsheng@627: "This behaviour, of changes to a file propagating out to copies of the file, " dongsheng@627: "might seem esoteric, but in most cases it's highly desirable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:284 dongsheng@627: msgid "" dongsheng@627: "First of all, remember that this propagation <emphasis>only</emphasis> " dongsheng@627: "happens when you merge. So if you <command role=\"hg-cmd\">hg copy</command> " dongsheng@627: "a file, and subsequently modify the original file during the normal course of " dongsheng@627: "your work, nothing will happen." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:290 dongsheng@627: msgid "" dongsheng@627: "The second thing to know is that modifications will only propagate across a " dongsheng@627: "copy as long as the repository that you're pulling changes from " dongsheng@627: "<emphasis>doesn't know</emphasis> about the copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:295 dongsheng@627: msgid "" dongsheng@627: "The reason that Mercurial does this is as follows. Let's say I make an " dongsheng@627: "important bug fix in a source file, and commit my changes. Meanwhile, you've " dongsheng@627: "decided to <command role=\"hg-cmd\">hg copy</command> the file in your " dongsheng@627: "repository, without knowing about the bug or having seen the fix, and you " dongsheng@627: "have started hacking on your copy of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:302 dongsheng@627: msgid "" dongsheng@627: "If you pulled and merged my changes, and Mercurial <emphasis>didn't</" dongsheng@627: "emphasis> propagate changes across copies, your source file would now contain " dongsheng@627: "the bug, and unless you remembered to propagate the bug fix by hand, the bug " dongsheng@627: "would <emphasis>remain</emphasis> in your copy of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:308 dongsheng@627: msgid "" dongsheng@627: "By automatically propagating the change that fixed the bug from the original " dongsheng@627: "file to the copy, Mercurial prevents this class of problem. To my knowledge, " dongsheng@627: "Mercurial is the <emphasis>only</emphasis> revision control system that " dongsheng@627: "propagates changes across copies like this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:314 dongsheng@627: msgid "" dongsheng@627: "Once your change history has a record that the copy and subsequent merge " dongsheng@627: "occurred, there's usually no further need to propagate changes from the " dongsheng@627: "original file to the copied file, and that's why Mercurial only propagates " dongsheng@627: "changes across copies until this point, and no further." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:322 dongsheng@627: msgid "How to make changes <emphasis>not</emphasis> follow a copy" dongsheng@627: msgstr "如何让复制后<emphasis>不</emphasis>修改?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:325 dongsheng@627: msgid "" dongsheng@627: "If, for some reason, you decide that this business of automatically " dongsheng@627: "propagating changes across copies is not for you, simply use your system's " dongsheng@627: "normal file copy command (on Unix-like systems, that's <command>cp</command>) " dongsheng@627: "to make a copy of a file, then <command role=\"hg-cmd\">hg add</command> the " dongsheng@627: "new copy by hand. Before you do so, though, please do reread section <xref " dongsheng@627: "linkend=\"sec.daily.why-copy\"/>, and make an informed decision that this " dongsheng@627: "behaviour is not appropriate to your specific case." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:338 dongsheng@627: msgid "Behaviour of the <command role=\"hg-cmd\">hg copy</command> command" dongsheng@627: msgstr "命令 <command role=\"hg-cmd\">hg copy</command> 的特性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:341 dongsheng@627: msgid "" dongsheng@627: "When you use the <command role=\"hg-cmd\">hg copy</command> command, " dongsheng@627: "Mercurial makes a copy of each source file as it currently stands in the " dongsheng@627: "working directory. This means that if you make some modifications to a file, " dongsheng@627: "then <command role=\"hg-cmd\">hg copy</command> it without first having " dongsheng@627: "committed those changes, the new copy will also contain the modifications you " dongsheng@627: "have made up until that point. (I find this behaviour a little " dongsheng@627: "counterintuitive, which is why I mention it here.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:351 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg copy</command> command acts similarly to the " dongsheng@627: "Unix <command>cp</command> command (you can use the <command role=\"hg-cmd" dongsheng@627: "\">hg cp</command> alias if you prefer). The last argument is the " dongsheng@627: "<emphasis>destination</emphasis>, and all prior arguments are " dongsheng@627: "<emphasis>sources</emphasis>. If you pass it a single file as the source, " dongsheng@627: "and the destination does not exist, it creates a new file with that name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:362 dongsheng@627: msgid "" dongsheng@627: "If the destination is a directory, Mercurial copies its sources into that " dongsheng@627: "directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:367 dongsheng@627: msgid "" dongsheng@627: "Copying a directory is recursive, and preserves the directory structure of " dongsheng@627: "the source." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:373 dongsheng@627: msgid "" dongsheng@627: "If the source and destination are both directories, the source tree is " dongsheng@627: "recreated in the destination directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:378 dongsheng@627: msgid "" dongsheng@627: "As with the <command role=\"hg-cmd\">hg rename</command> command, if you copy " dongsheng@627: "a file manually and then want Mercurial to know that you've copied the file, " dongsheng@627: "simply use the <option role=\"hg-opt-copy\">--after</option> option to " dongsheng@627: "<command role=\"hg-cmd\">hg copy</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:389 dongsheng@627: msgid "Renaming files" dongsheng@627: msgstr "改名文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:391 dongsheng@627: msgid "" dongsheng@627: "It's rather more common to need to rename a file than to make a copy of it. " dongsheng@627: "The reason I discussed the <command role=\"hg-cmd\">hg copy</command> command " dongsheng@627: "before talking about renaming files is that Mercurial treats a rename in " dongsheng@627: "essentially the same way as a copy. Therefore, knowing what Mercurial does " dongsheng@627: "when you copy a file tells you what to expect when you rename a file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:399 dongsheng@627: msgid "" dongsheng@627: "When you use the <command role=\"hg-cmd\">hg rename</command> command, " dongsheng@627: "Mercurial makes a copy of each source file, then deletes it and marks the " dongsheng@627: "file as removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:405 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg status</command> command shows the newly " dongsheng@627: "copied file as added, and the copied-from file as removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:411 dongsheng@627: msgid "" dongsheng@627: "As with the results of a <command role=\"hg-cmd\">hg copy</command>, we must " dongsheng@627: "use the <option role=\"hg-opt-status\">-C</option> option to <command role=" dongsheng@627: "\"hg-cmd\">hg status</command> to see that the added file is really being " dongsheng@627: "tracked by Mercurial as a copy of the original, now removed, file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:420 dongsheng@627: msgid "" dongsheng@627: "As with <command role=\"hg-cmd\">hg remove</command> and <command role=\"hg-" dongsheng@627: "cmd\">hg copy</command>, you can tell Mercurial about a rename after the fact " dongsheng@627: "using the <option role=\"hg-opt-rename\">--after</option> option. In most " dongsheng@627: "other respects, the behaviour of the <command role=\"hg-cmd\">hg rename</" dongsheng@627: "command> command, and the options it accepts, are similar to the <command " dongsheng@627: "role=\"hg-cmd\">hg copy</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:430 dongsheng@627: msgid "Renaming files and merging changes" dongsheng@627: msgstr "改名文件与合并修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:432 dongsheng@627: msgid "" dongsheng@627: "Since Mercurial's rename is implemented as copy-and-remove, the same " dongsheng@627: "propagation of changes happens when you merge after a rename as after a copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:436 dongsheng@627: msgid "" dongsheng@627: "If I modify a file, and you rename it to a new name, and then we merge our " dongsheng@627: "respective changes, my modifications to the file under its original name will " dongsheng@627: "be propagated into the file under its new name. (This is something you might " dongsheng@627: "expect to <quote>simply work,</quote> but not all revision control systems " dongsheng@627: "actually do this.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:443 dongsheng@627: msgid "" dongsheng@627: "Whereas having changes follow a copy is a feature where you can perhaps nod " dongsheng@627: "and say <quote>yes, that might be useful,</quote> it should be clear that " dongsheng@627: "having them follow a rename is definitely important. Without this facility, " dongsheng@627: "it would simply be too easy for changes to become orphaned when files are " dongsheng@627: "renamed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:452 dongsheng@627: msgid "Divergent renames and merging" dongsheng@627: msgstr "改名与合并的分歧" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:454 dongsheng@627: msgid "" dongsheng@627: "The case of diverging names occurs when two developers start with a " dongsheng@627: "file&emdash;let's call it <filename>foo</filename>&emdash;in their respective " dongsheng@627: "repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:461 dongsheng@627: msgid "Anne renames the file to <filename>bar</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:465 dongsheng@627: msgid "Meanwhile, Bob renames it to <filename>quux</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:470 dongsheng@627: msgid "" dongsheng@627: "I like to think of this as a conflict because each developer has expressed " dongsheng@627: "different intentions about what the file ought to be named." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:474 dongsheng@627: msgid "" dongsheng@627: "What do you think should happen when they merge their work? Mercurial's " dongsheng@627: "actual behaviour is that it always preserves <emphasis>both</emphasis> names " dongsheng@627: "when it merges changesets that contain divergent renames." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:481 dongsheng@627: msgid "" dongsheng@627: "Notice that Mercurial does warn about the divergent renames, but it leaves it " dongsheng@627: "up to you to do something about the divergence after the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:487 dongsheng@627: msgid "Convergent renames and merging" dongsheng@627: msgstr "收敛改名与合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:489 dongsheng@627: msgid "" dongsheng@627: "Another kind of rename conflict occurs when two people choose to rename " dongsheng@627: "different <emphasis>source</emphasis> files to the same " dongsheng@627: "<emphasis>destination</emphasis>. In this case, Mercurial runs its normal " dongsheng@627: "merge machinery, and lets you guide it to a suitable resolution." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch05-daily.xml:497 dongsheng@627: msgid "Other name-related corner cases" dongsheng@627: msgstr "其它名称相关的角落" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch05-daily.xml:499 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a longstanding bug in which it fails to handle a merge where " dongsheng@627: "one side has a file with a given name, while another has a directory with the " dongsheng@627: "same name. This is documented as <ulink role=\"hg-bug\" url=\"http://www." dongsheng@627: "selenic.com/mercurial/bts/issue29\">issue 29</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch05-daily.xml:511 dongsheng@627: msgid "Recovering from mistakes" dongsheng@627: msgstr "从错误恢复" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:513 dongsheng@627: msgid "" dongsheng@627: "Mercurial has some useful commands that will help you to recover from some " dongsheng@627: "common mistakes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:516 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg revert</command> command lets you undo " dongsheng@627: "changes that you have made to your working directory. For example, if you " dongsheng@627: "<command role=\"hg-cmd\">hg add</command> a file by accident, just run " dongsheng@627: "<command role=\"hg-cmd\">hg revert</command> with the name of the file you " dongsheng@627: "added, and while the file won't be touched in any way, it won't be tracked " dongsheng@627: "for adding by Mercurial any longer, either. You can also use <command role=" dongsheng@627: "\"hg-cmd\">hg revert</command> to get rid of erroneous changes to a file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:526 dongsheng@627: msgid "" dongsheng@627: "It's useful to remember that the <command role=\"hg-cmd\">hg revert</command> " dongsheng@627: "command is useful for changes that you have not yet committed. Once you've " dongsheng@627: "committed a change, if you decide it was a mistake, you can still do " dongsheng@627: "something about it, though your options may be more limited." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch05-daily.xml:532 dongsheng@627: msgid "" dongsheng@627: "For more information about the <command role=\"hg-cmd\">hg revert</command> " dongsheng@627: "command, and details about how to deal with changes you have already " dongsheng@627: "committed, see chapter <xref linkend=\"chap.undo\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch06-collab.xml:5 dongsheng@627: msgid "Collaborating with other people" dongsheng@627: msgstr "团体协作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch06-collab.xml:7 dongsheng@627: msgid "" dongsheng@627: "As a completely decentralised tool, Mercurial doesn't impose any policy on " dongsheng@627: "how people ought to work with each other. However, if you're new to " dongsheng@627: "distributed revision control, it helps to have some tools and examples in " dongsheng@627: "mind when you're thinking about possible workflow models." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:14 dongsheng@627: msgid "Mercurial's web interface" dongsheng@630: msgstr "Mercurial 的 web 接口" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:16 dongsheng@627: msgid "" dongsheng@627: "Mercurial has a powerful web interface that provides several useful " dongsheng@627: "capabilities." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:19 dongsheng@627: msgid "" dongsheng@627: "For interactive use, the web interface lets you browse a single repository or " dongsheng@627: "a collection of repositories. You can view the history of a repository, " dongsheng@627: "examine each change (comments and diffs), and view the contents of each " dongsheng@627: "directory and file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:24 dongsheng@627: msgid "" dongsheng@627: "Also for human consumption, the web interface provides an RSS feed of the " dongsheng@627: "changes in a repository. This lets you <quote>subscribe</quote> to a " dongsheng@627: "repository using your favourite feed reader, and be automatically notified of " dongsheng@627: "activity in that repository as soon as it happens. I find this capability " dongsheng@627: "much more convenient than the model of subscribing to a mailing list to which " dongsheng@627: "notifications are sent, as it requires no additional configuration on the " dongsheng@627: "part of whoever is serving the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:34 dongsheng@627: msgid "" dongsheng@627: "The web interface also lets remote users clone a repository, pull changes " dongsheng@627: "from it, and (when the server is configured to permit it) push changes back " dongsheng@627: "to it. Mercurial's HTTP tunneling protocol aggressively compresses data, so " dongsheng@627: "that it works efficiently even over low-bandwidth network connections." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:40 dongsheng@627: msgid "" dongsheng@627: "The easiest way to get started with the web interface is to use your web " dongsheng@627: "browser to visit an existing repository, such as the master Mercurial " dongsheng@627: "repository at <ulink url=\"http://www.selenic.com/repo/hg?style=gitweb" dongsheng@627: "\">http://www.selenic.com/repo/hg?style=gitweb</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:45 dongsheng@627: msgid "" dongsheng@627: "If you're interested in providing a web interface to your own repositories, " dongsheng@627: "Mercurial provides two ways to do this. The first is using the <command role=" dongsheng@627: "\"hg-cmd\">hg serve</command> command, which is best suited to short-term " dongsheng@627: "<quote>lightweight</quote> serving. See section <xref linkend=\"sec.collab." dongsheng@627: "serve\"/> below for details of how to use this command. If you have a long-" dongsheng@627: "lived repository that you'd like to make permanently available, Mercurial has " dongsheng@627: "built-in support for the CGI (Common Gateway Interface) standard, which all " dongsheng@627: "common web servers support. See section <xref linkend=\"sec.collab.cgi\"/> " dongsheng@627: "for details of CGI configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:60 dongsheng@627: msgid "Collaboration models" dongsheng@630: msgstr "协作模型" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:62 dongsheng@627: msgid "" dongsheng@627: "With a suitably flexible tool, making decisions about workflow is much more " dongsheng@627: "of a social engineering challenge than a technical one. Mercurial imposes few " dongsheng@627: "limitations on how you can structure the flow of work in a project, so it's " dongsheng@627: "up to you and your group to set up and live with a model that matches your " dongsheng@627: "own particular needs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:70 dongsheng@627: msgid "Factors to keep in mind" dongsheng@630: msgstr "要牢记的因素" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:72 dongsheng@627: msgid "" dongsheng@627: "The most important aspect of any model that you must keep in mind is how well " dongsheng@627: "it matches the needs and capabilities of the people who will be using it. " dongsheng@627: "This might seem self-evident; even so, you still can't afford to forget it " dongsheng@627: "for a moment." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:78 dongsheng@627: msgid "" dongsheng@627: "I once put together a workflow model that seemed to make perfect sense to me, " dongsheng@627: "but that caused a considerable amount of consternation and strife within my " dongsheng@627: "development team. In spite of my attempts to explain why we needed a complex " dongsheng@627: "set of branches, and how changes ought to flow between them, a few team " dongsheng@627: "members revolted. Even though they were smart people, they didn't want to " dongsheng@627: "pay attention to the constraints we were operating under, or face the " dongsheng@627: "consequences of those constraints in the details of the model that I was " dongsheng@627: "advocating." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:88 dongsheng@627: msgid "" dongsheng@627: "Don't sweep foreseeable social or technical problems under the rug. Whatever " dongsheng@627: "scheme you put into effect, you should plan for mistakes and problem " dongsheng@627: "scenarios. Consider adding automated machinery to prevent, or quickly " dongsheng@627: "recover from, trouble that you can anticipate. As an example, if you intend " dongsheng@627: "to have a branch with not-for-release changes in it, you'd do well to think " dongsheng@627: "early about the possibility that someone might accidentally merge those " dongsheng@627: "changes into a release branch. You could avoid this particular problem by " dongsheng@627: "writing a hook that prevents changes from being merged from an inappropriate " dongsheng@627: "branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:102 dongsheng@627: msgid "Informal anarchy" dongsheng@630: msgstr "无政府状态" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:104 dongsheng@627: msgid "" dongsheng@627: "I wouldn't suggest an <quote>anything goes</quote> approach as something " dongsheng@627: "sustainable, but it's a model that's easy to grasp, and it works perfectly " dongsheng@627: "well in a few unusual situations." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:109 dongsheng@627: msgid "" dongsheng@627: "As one example, many projects have a loose-knit group of collaborators who " dongsheng@627: "rarely physically meet each other. Some groups like to overcome the " dongsheng@627: "isolation of working at a distance by organising occasional <quote>sprints</" dongsheng@627: "quote>. In a sprint, a number of people get together in a single location (a " dongsheng@627: "company's conference room, a hotel meeting room, that kind of place) and " dongsheng@627: "spend several days more or less locked in there, hacking intensely on a " dongsheng@627: "handful of projects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:118 dongsheng@627: msgid "" dongsheng@627: "A sprint is the perfect place to use the <command role=\"hg-cmd\">hg serve</" dongsheng@627: "command> command, since <command role=\"hg-cmd\">hg serve</command> does not " dongsheng@627: "require any fancy server infrastructure. You can get started with <command " dongsheng@627: "role=\"hg-cmd\">hg serve</command> in moments, by reading section <xref " dongsheng@627: "linkend=\"sec.collab.serve\"/> below. Then simply tell the person next to " dongsheng@627: "you that you're running a server, send the URL to them in an instant message, " dongsheng@627: "and you immediately have a quick-turnaround way to work together. They can " dongsheng@627: "type your URL into their web browser and quickly review your changes; or they " dongsheng@627: "can pull a bugfix from you and verify it; or they can clone a branch " dongsheng@627: "containing a new feature and try it out." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:132 dongsheng@627: msgid "" dongsheng@627: "The charm, and the problem, with doing things in an ad hoc fashion like this " dongsheng@627: "is that only people who know about your changes, and where they are, can see " dongsheng@627: "them. Such an informal approach simply doesn't scale beyond a handful " dongsheng@627: "people, because each individual needs to know about $n$ different " dongsheng@627: "repositories to pull from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:141 dongsheng@627: msgid "A single central repository" dongsheng@630: msgstr "单一中央版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:143 dongsheng@627: msgid "" dongsheng@627: "For smaller projects migrating from a centralised revision control tool, " dongsheng@627: "perhaps the easiest way to get started is to have changes flow through a " dongsheng@627: "single shared central repository. This is also the most common " dongsheng@627: "<quote>building block</quote> for more ambitious workflow schemes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:149 dongsheng@627: msgid "" dongsheng@627: "Contributors start by cloning a copy of this repository. They can pull " dongsheng@627: "changes from it whenever they need to, and some (perhaps all) developers have " dongsheng@627: "permission to push a change back when they're ready for other people to see " dongsheng@627: "it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:154 dongsheng@627: msgid "" dongsheng@627: "Under this model, it can still often make sense for people to pull changes " dongsheng@627: "directly from each other, without going through the central repository. " dongsheng@627: "Consider a case in which I have a tentative bug fix, but I am worried that if " dongsheng@627: "I were to publish it to the central repository, it might subsequently break " dongsheng@627: "everyone else's trees as they pull it. To reduce the potential for damage, I " dongsheng@627: "can ask you to clone my repository into a temporary repository of your own " dongsheng@627: "and test it. This lets us put off publishing the potentially unsafe change " dongsheng@627: "until it has had a little testing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:165 dongsheng@627: msgid "" dongsheng@627: "In this kind of scenario, people usually use the <command>ssh</command> " dongsheng@627: "protocol to securely push changes to the central repository, as documented in " dongsheng@627: "section <xref linkend=\"sec.collab.ssh\"/>. It's also usual to publish a " dongsheng@627: "read-only copy of the repository over HTTP using CGI, as in section <xref " dongsheng@627: "linkend=\"sec.collab.cgi\"/>. Publishing over HTTP satisfies the needs of " dongsheng@627: "people who don't have push access, and those who want to use web browsers to " dongsheng@627: "browse the repository's history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:178 dongsheng@627: msgid "Working with multiple branches" dongsheng@630: msgstr "使用多个分支工作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:180 dongsheng@627: msgid "" dongsheng@627: "Projects of any significant size naturally tend to make progress on several " dongsheng@627: "fronts simultaneously. In the case of software, it's common for a project to " dongsheng@627: "go through periodic official releases. A release might then go into " dongsheng@627: "<quote>maintenance mode</quote> for a while after its first publication; " dongsheng@627: "maintenance releases tend to contain only bug fixes, not new features. In " dongsheng@627: "parallel with these maintenance releases, one or more future releases may be " dongsheng@627: "under development. People normally use the word <quote>branch</quote> to " dongsheng@627: "refer to one of these many slightly different directions in which development " dongsheng@627: "is proceeding." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:193 dongsheng@627: msgid "" dongsheng@627: "Mercurial is particularly well suited to managing a number of simultaneous, " dongsheng@627: "but not identical, branches. Each <quote>development direction</quote> can " dongsheng@627: "live in its own central repository, and you can merge changes from one to " dongsheng@627: "another as the need arises. Because repositories are independent of each " dongsheng@627: "other, unstable changes in a development branch will never affect a stable " dongsheng@627: "branch unless someone explicitly merges those changes in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:202 dongsheng@627: msgid "" dongsheng@627: "Here's an example of how this can work in practice. Let's say you have one " dongsheng@627: "<quote>main branch</quote> on a central server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:208 dongsheng@627: msgid "People clone it, make changes locally, test them, and push them back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:211 dongsheng@627: msgid "" dongsheng@627: "Once the main branch reaches a release milestone, you can use the <command " dongsheng@627: "role=\"hg-cmd\">hg tag</command> command to give a permanent name to the " dongsheng@627: "milestone revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:217 dongsheng@627: msgid "Let's say some ongoing development occurs on the main branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:222 dongsheng@627: msgid "" dongsheng@627: "Using the tag that was recorded at the milestone, people who clone that " dongsheng@627: "repository at any time in the future can use <command role=\"hg-cmd\">hg " dongsheng@627: "update</command> to get a copy of the working directory exactly as it was " dongsheng@627: "when that tagged revision was committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:230 dongsheng@627: msgid "" dongsheng@627: "In addition, immediately after the main branch is tagged, someone can then " dongsheng@627: "clone the main branch on the server to a new <quote>stable</quote> branch, " dongsheng@627: "also on the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:236 dongsheng@627: msgid "" dongsheng@627: "Someone who needs to make a change to the stable branch can then clone " dongsheng@627: "<emphasis>that</emphasis> repository, make their changes, commit, and push " dongsheng@627: "their changes back there." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:242 dongsheng@627: msgid "" dongsheng@627: "Because Mercurial repositories are independent, and Mercurial doesn't move " dongsheng@627: "changes around automatically, the stable and main branches are " dongsheng@627: "<emphasis>isolated</emphasis> from each other. The changes that you made on " dongsheng@627: "the main branch don't <quote>leak</quote> to the stable branch, and vice " dongsheng@627: "versa." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:249 dongsheng@627: msgid "" dongsheng@627: "You'll often want all of your bugfixes on the stable branch to show up on the " dongsheng@627: "main branch, too. Rather than rewrite a bugfix on the main branch, you can " dongsheng@627: "simply pull and merge changes from the stable to the main branch, and " dongsheng@627: "Mercurial will bring those bugfixes in for you." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:257 dongsheng@627: msgid "" dongsheng@627: "The main branch will still contain changes that are not on the stable branch, " dongsheng@627: "but it will also contain all of the bugfixes from the stable branch. The " dongsheng@627: "stable branch remains unaffected by these changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch06-collab.xml:264 ../en/ch06-collab.xml:276 dongsheng@627: msgid "Feature branches" dongsheng@630: msgstr "特性分支" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:266 dongsheng@627: msgid "" dongsheng@627: "For larger projects, an effective way to manage change is to break up a team " dongsheng@627: "into smaller groups. Each group has a shared branch of its own, cloned from " dongsheng@627: "a single <quote>master</quote> branch used by the entire project. People " dongsheng@627: "working on an individual branch are typically quite isolated from " dongsheng@627: "developments on other branches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch06-collab.xml:274 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/feature-branches.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:280 dongsheng@627: msgid "" dongsheng@627: "When a particular feature is deemed to be in suitable shape, someone on that " dongsheng@627: "feature team pulls and merges from the master branch into the feature branch, " dongsheng@627: "then pushes back up to the master branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:287 dongsheng@627: msgid "The release train" dongsheng@630: msgstr "发布列车" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:289 dongsheng@627: msgid "" dongsheng@627: "Some projects are organised on a <quote>train</quote> basis: a release is " dongsheng@627: "scheduled to happen every few months, and whatever features are ready when " dongsheng@627: "the <quote>train</quote> is ready to leave are allowed in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:294 dongsheng@627: msgid "" dongsheng@627: "This model resembles working with feature branches. The difference is that " dongsheng@627: "when a feature branch misses a train, someone on the feature team pulls and " dongsheng@627: "merges the changes that went out on that train release into the feature " dongsheng@627: "branch, and the team continues its work on top of that release so that their " dongsheng@627: "feature can make the next release." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:303 dongsheng@627: msgid "The Linux kernel model" dongsheng@630: msgstr "Linux 内核模型" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:305 dongsheng@627: msgid "" dongsheng@627: "The development of the Linux kernel has a shallow hierarchical structure, " dongsheng@627: "surrounded by a cloud of apparent chaos. Because most Linux developers use " dongsheng@627: "<command>git</command>, a distributed revision control tool with capabilities " dongsheng@627: "similar to Mercurial, it's useful to describe the way work flows in that " dongsheng@627: "environment; if you like the ideas, the approach translates well across tools." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:313 dongsheng@627: msgid "" dongsheng@627: "At the center of the community sits Linus Torvalds, the creator of Linux. He " dongsheng@627: "publishes a single source repository that is considered the " dongsheng@627: "<quote>authoritative</quote> current tree by the entire developer community. " dongsheng@627: "Anyone can clone Linus's tree, but he is very choosy about whose trees he " dongsheng@627: "pulls from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:320 dongsheng@627: msgid "" dongsheng@627: "Linus has a number of <quote>trusted lieutenants</quote>. As a general rule, " dongsheng@627: "he pulls whatever changes they publish, in most cases without even reviewing " dongsheng@627: "those changes. Some of those lieutenants are generally agreed to be " dongsheng@627: "<quote>maintainers</quote>, responsible for specific subsystems within the " dongsheng@627: "kernel. If a random kernel hacker wants to make a change to a subsystem that " dongsheng@627: "they want to end up in Linus's tree, they must find out who the subsystem's " dongsheng@627: "maintainer is, and ask that maintainer to take their change. If the " dongsheng@627: "maintainer reviews their changes and agrees to take them, they'll pass them " dongsheng@627: "along to Linus in due course." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:332 dongsheng@627: msgid "" dongsheng@627: "Individual lieutenants have their own approaches to reviewing, accepting, and " dongsheng@627: "publishing changes; and for deciding when to feed them to Linus. In " dongsheng@627: "addition, there are several well known branches that people use for different " dongsheng@627: "purposes. For example, a few people maintain <quote>stable</quote> " dongsheng@627: "repositories of older versions of the kernel, to which they apply critical " dongsheng@627: "fixes as needed. Some maintainers publish multiple trees: one for " dongsheng@627: "experimental changes; one for changes that they are about to feed upstream; " dongsheng@627: "and so on. Others just publish a single tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:343 dongsheng@627: msgid "" dongsheng@627: "This model has two notable features. The first is that it's <quote>pull " dongsheng@627: "only</quote>. You have to ask, convince, or beg another developer to take a " dongsheng@627: "change from you, because there are almost no trees to which more than one " dongsheng@627: "person can push, and there's no way to push changes into a tree that someone " dongsheng@627: "else controls." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:350 dongsheng@627: msgid "" dongsheng@627: "The second is that it's based on reputation and acclaim. If you're an " dongsheng@627: "unknown, Linus will probably ignore changes from you without even " dongsheng@627: "responding. But a subsystem maintainer will probably review them, and will " dongsheng@627: "likely take them if they pass their criteria for suitability. The more " dongsheng@627: "<quote>good</quote> changes you contribute to a maintainer, the more likely " dongsheng@627: "they are to trust your judgment and accept your changes. If you're well-" dongsheng@627: "known and maintain a long-lived branch for something Linus hasn't yet " dongsheng@627: "accepted, people with similar interests may pull your changes regularly to " dongsheng@627: "keep up with your work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:361 dongsheng@627: msgid "" dongsheng@627: "Reputation and acclaim don't necessarily cross subsystem or <quote>people</" dongsheng@627: "quote> boundaries. If you're a respected but specialised storage hacker, and " dongsheng@627: "you try to fix a networking bug, that change will receive a level of scrutiny " dongsheng@627: "from a network maintainer comparable to a change from a complete stranger." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:368 dongsheng@627: msgid "" dongsheng@627: "To people who come from more orderly project backgrounds, the comparatively " dongsheng@627: "chaotic Linux kernel development process often seems completely insane. It's " dongsheng@627: "subject to the whims of individuals; people make sweeping changes whenever " dongsheng@627: "they deem it appropriate; and the pace of development is astounding. And yet " dongsheng@627: "Linux is a highly successful, well-regarded piece of software." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:378 dongsheng@627: msgid "Pull-only versus shared-push collaboration" dongsheng@630: msgstr "只读与共享写协作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:380 dongsheng@627: msgid "" dongsheng@627: "A perpetual source of heat in the open source community is whether a " dongsheng@627: "development model in which people only ever pull changes from others is " dongsheng@627: "<quote>better than</quote> one in which multiple people can push changes to a " dongsheng@627: "shared repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:386 dongsheng@627: msgid "" dongsheng@627: "Typically, the backers of the shared-push model use tools that actively " dongsheng@627: "enforce this approach. If you're using a centralised revision control tool " dongsheng@627: "such as Subversion, there's no way to make a choice over which model you'll " dongsheng@627: "use: the tool gives you shared-push, and if you want to do anything else, " dongsheng@627: "you'll have to roll your own approach on top (such as applying a patch by " dongsheng@627: "hand)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:394 dongsheng@627: msgid "" dongsheng@627: "A good distributed revision control tool, such as Mercurial, will support " dongsheng@627: "both models. You and your collaborators can then structure how you work " dongsheng@627: "together based on your own needs and preferences, not on what contortions " dongsheng@627: "your tools force you into." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:402 dongsheng@627: msgid "Where collaboration meets branch management" dongsheng@630: msgstr "协作与分支管理" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:404 dongsheng@627: msgid "" dongsheng@627: "Once you and your team set up some shared repositories and start propagating " dongsheng@627: "changes back and forth between local and shared repos, you begin to face a " dongsheng@627: "related, but slightly different challenge: that of managing the multiple " dongsheng@627: "directions in which your team may be moving at once. Even though this " dongsheng@627: "subject is intimately related to how your team collaborates, it's dense " dongsheng@627: "enough to merit treatment of its own, in chapter <xref linkend=\"chap.branch" dongsheng@627: "\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:416 dongsheng@627: msgid "The technical side of sharing" dongsheng@630: msgstr "共享的技术因素" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:418 dongsheng@627: msgid "" dongsheng@627: "The remainder of this chapter is devoted to the question of serving data to " dongsheng@627: "your collaborators." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:423 dongsheng@627: msgid "Informal sharing with <command role=\"hg-cmd\">hg serve</command>" dongsheng@630: msgstr "使用 <command role=\"hg-cmd\">hg serve</command> 进行非正式共享" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:426 dongsheng@627: msgid "" dongsheng@627: "Mercurial's <command role=\"hg-cmd\">hg serve</command> command is " dongsheng@627: "wonderfully suited to small, tight-knit, and fast-paced group environments. " dongsheng@627: "It also provides a great way to get a feel for using Mercurial commands over " dongsheng@627: "a network." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:431 dongsheng@627: msgid "" dongsheng@627: "Run <command role=\"hg-cmd\">hg serve</command> inside a repository, and in " dongsheng@627: "under a second it will bring up a specialised HTTP server; this will accept " dongsheng@627: "connections from any client, and serve up data for that repository until you " dongsheng@627: "terminate it. Anyone who knows the URL of the server you just started, and " dongsheng@627: "can talk to your computer over the network, can then use a web browser or " dongsheng@627: "Mercurial to read data from that repository. A URL for a <command role=\"hg-" dongsheng@627: "cmd\">hg serve</command> instance running on a laptop is likely to look " dongsheng@627: "something like <literal>http://my-laptop.local:8000/</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:442 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg serve</command> command is <emphasis>not</" dongsheng@627: "emphasis> a general-purpose web server. It can do only two things:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:446 dongsheng@627: msgid "" dongsheng@627: "Allow people to browse the history of the repository it's serving, from their " dongsheng@627: "normal web browsers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:450 dongsheng@627: msgid "" dongsheng@627: "Speak Mercurial's wire protocol, so that people can <command role=\"hg-cmd" dongsheng@627: "\">hg clone</command> or <command role=\"hg-cmd\">hg pull</command> changes " dongsheng@627: "from that repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:455 dongsheng@627: msgid "" dongsheng@627: "In particular, <command role=\"hg-cmd\">hg serve</command> won't allow remote " dongsheng@627: "users to <emphasis>modify</emphasis> your repository. It's intended for read-" dongsheng@627: "only use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:459 dongsheng@627: msgid "" dongsheng@627: "If you're getting started with Mercurial, there's nothing to prevent you from " dongsheng@627: "using <command role=\"hg-cmd\">hg serve</command> to serve up a repository on " dongsheng@627: "your own computer, then use commands like <command role=\"hg-cmd\">hg clone</" dongsheng@627: "command>, <command role=\"hg-cmd\">hg incoming</command>, and so on to talk " dongsheng@627: "to that server as if the repository was hosted remotely. This can help you to " dongsheng@627: "quickly get acquainted with using commands on network-hosted repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:469 dongsheng@627: msgid "A few things to keep in mind" dongsheng@630: msgstr "要牢记的几件事" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:471 dongsheng@627: msgid "" dongsheng@627: "Because it provides unauthenticated read access to all clients, you should " dongsheng@627: "only use <command role=\"hg-cmd\">hg serve</command> in an environment where " dongsheng@627: "you either don't care, or have complete control over, who can access your " dongsheng@627: "network and pull data from your repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:477 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg serve</command> command knows nothing about " dongsheng@627: "any firewall software you might have installed on your system or network. It " dongsheng@627: "cannot detect or control your firewall software. If other people are unable " dongsheng@627: "to talk to a running <command role=\"hg-cmd\">hg serve</command> instance, " dongsheng@627: "the second thing you should do (<emphasis>after</emphasis> you make sure that " dongsheng@627: "they're using the correct URL) is check your firewall configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:486 dongsheng@627: msgid "" dongsheng@627: "By default, <command role=\"hg-cmd\">hg serve</command> listens for incoming " dongsheng@627: "connections on port 8000. If another process is already listening on the " dongsheng@627: "port you want to use, you can specify a different port to listen on using the " dongsheng@627: "<option role=\"hg-opt-serve\">-p</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:492 dongsheng@627: msgid "" dongsheng@627: "Normally, when <command role=\"hg-cmd\">hg serve</command> starts, it prints " dongsheng@627: "no output, which can be a bit unnerving. If you'd like to confirm that it is " dongsheng@627: "indeed running correctly, and find out what URL you should send to your " dongsheng@627: "collaborators, start it with the <option role=\"hg-opt-global\">-v</option> " dongsheng@627: "option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:502 dongsheng@627: msgid "Using the Secure Shell (ssh) protocol" dongsheng@630: msgstr "使用 ssh 协议" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:504 dongsheng@627: msgid "" dongsheng@627: "You can pull and push changes securely over a network connection using the " dongsheng@627: "Secure Shell (<literal>ssh</literal>) protocol. To use this successfully, " dongsheng@627: "you may have to do a little bit of configuration on the client or server " dongsheng@627: "sides." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:509 dongsheng@627: msgid "" dongsheng@627: "If you're not familiar with ssh, it's a network protocol that lets you " dongsheng@627: "securely communicate with another computer. To use it with Mercurial, you'll " dongsheng@627: "be setting up one or more user accounts on a server so that remote users can " dongsheng@627: "log in and execute commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:515 dongsheng@627: msgid "" dongsheng@627: "(If you <emphasis>are</emphasis> familiar with ssh, you'll probably find some " dongsheng@627: "of the material that follows to be elementary in nature.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:520 dongsheng@627: msgid "How to read and write ssh URLs" dongsheng@630: msgstr "如何读写 ssh 路径" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:522 dongsheng@627: msgid "An ssh URL tends to look like this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:525 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>ssh://</literal></quote> part tells Mercurial to use the " dongsheng@627: "ssh protocol." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:528 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>bos@</literal></quote> component indicates what username " dongsheng@627: "to log into the server as. You can leave this out if the remote username is " dongsheng@627: "the same as your local username." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:533 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>hg.serpentine.com</literal></quote> gives the hostname of " dongsheng@627: "the server to log into." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:537 dongsheng@627: msgid "" dongsheng@627: "The <quote>:22</quote> identifies the port number to connect to the server " dongsheng@627: "on. The default port is 22, so you only need to specify this part if you're " dongsheng@627: "<emphasis>not</emphasis> using port 22." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:542 dongsheng@627: msgid "" dongsheng@627: "The remainder of the URL is the local path to the repository on the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:546 dongsheng@627: msgid "" dongsheng@627: "There's plenty of scope for confusion with the path component of ssh URLs, as " dongsheng@627: "there is no standard way for tools to interpret it. Some programs behave " dongsheng@627: "differently than others when dealing with these paths. This isn't an ideal " dongsheng@627: "situation, but it's unlikely to change. Please read the following paragraphs " dongsheng@627: "carefully." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:553 dongsheng@627: msgid "" dongsheng@627: "Mercurial treats the path to a repository on the server as relative to the " dongsheng@627: "remote user's home directory. For example, if user <literal>foo</literal> on " dongsheng@627: "the server has a home directory of <filename class=\"directory\">/home/foo</" dongsheng@627: "filename>, then an ssh URL that contains a path component of <filename class=" dongsheng@627: "\"directory\">bar</filename> <emphasis>really</emphasis> refers to the " dongsheng@627: "directory <filename class=\"directory\">/home/foo/bar</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:562 dongsheng@627: msgid "" dongsheng@627: "If you want to specify a path relative to another user's home directory, you " dongsheng@627: "can use a path that starts with a tilde character followed by the user's name " dongsheng@627: "(let's call them <literal>otheruser</literal>), like this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:568 dongsheng@627: msgid "" dongsheng@627: "And if you really want to specify an <emphasis>absolute</emphasis> path on " dongsheng@627: "the server, begin the path component with two slashes, as in this example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:575 dongsheng@627: msgid "Finding an ssh client for your system" dongsheng@630: msgstr "为你的系统寻找 ssh 客户端" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:577 dongsheng@627: msgid "" dongsheng@627: "Almost every Unix-like system comes with OpenSSH preinstalled. If you're " dongsheng@627: "using such a system, run <literal>which ssh</literal> to find out if the " dongsheng@627: "<command>ssh</command> command is installed (it's usually in <filename class=" dongsheng@627: "\"directory\">/usr/bin</filename>). In the unlikely event that it isn't " dongsheng@627: "present, take a look at your system documentation to figure out how to " dongsheng@627: "install it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:585 dongsheng@627: msgid "" dongsheng@627: "On Windows, you'll first need to download a suitable ssh client. There are " dongsheng@627: "two alternatives." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:588 dongsheng@627: msgid "" dongsheng@627: "Simon Tatham's excellent PuTTY package <citation>web:putty</citation> " dongsheng@627: "provides a complete suite of ssh client commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:592 dongsheng@627: msgid "" dongsheng@627: "If you have a high tolerance for pain, you can use the Cygwin port of OpenSSH." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:595 dongsheng@627: msgid "" dongsheng@627: "In either case, you'll need to edit your \\hgini\\ file to tell Mercurial " dongsheng@627: "where to find the actual client command. For example, if you're using PuTTY, " dongsheng@627: "you'll need to use the <command>plink</command> command as a command-line ssh " dongsheng@627: "client." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch06-collab.xml:604 dongsheng@627: msgid "" dongsheng@627: "The path to <command>plink</command> shouldn't contain any whitespace " dongsheng@627: "characters, or Mercurial may not be able to run it correctly (so putting it " dongsheng@627: "in <filename class=\"directory\">C:\\\\Program Files</filename> is probably " dongsheng@627: "not a good idea)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:613 dongsheng@627: msgid "Generating a key pair" dongsheng@630: msgstr "产生密钥对" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:615 dongsheng@627: msgid "" dongsheng@627: "To avoid the need to repetitively type a password every time you need to use " dongsheng@627: "your ssh client, I recommend generating a key pair. On a Unix-like system, " dongsheng@627: "the <command>ssh-keygen</command> command will do the trick. On Windows, if " dongsheng@627: "you're using PuTTY, the <command>puttygen</command> command is what you'll " dongsheng@627: "need." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:623 dongsheng@627: msgid "" dongsheng@627: "When you generate a key pair, it's usually <emphasis>highly</emphasis> " dongsheng@627: "advisable to protect it with a passphrase. (The only time that you might not " dongsheng@627: "want to do this is when you're using the ssh protocol for automated tasks on " dongsheng@627: "a secure network.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:629 dongsheng@627: msgid "" dongsheng@627: "Simply generating a key pair isn't enough, however. You'll need to add the " dongsheng@627: "public key to the set of authorised keys for whatever user you're logging in " dongsheng@627: "remotely as. For servers using OpenSSH (the vast majority), this will mean " dongsheng@627: "adding the public key to a list in a file called <filename role=\"special" dongsheng@627: "\">authorized_keys</filename> in their <filename role=\"special\" class=" dongsheng@627: "\"directory\">.ssh</filename> directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:638 dongsheng@627: msgid "" dongsheng@627: "On a Unix-like system, your public key will have a <filename>.pub</filename> " dongsheng@627: "extension. If you're using <command>puttygen</command> on Windows, you can " dongsheng@627: "save the public key to a file of your choosing, or paste it from the window " dongsheng@627: "it's displayed in straight into the <filename role=\"special" dongsheng@627: "\">authorized_keys</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:647 dongsheng@627: msgid "Using an authentication agent" dongsheng@630: msgstr "使用认证代理" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:649 dongsheng@627: msgid "" dongsheng@627: "An authentication agent is a daemon that stores passphrases in memory (so it " dongsheng@627: "will forget passphrases if you log out and log back in again). An ssh client " dongsheng@627: "will notice if it's running, and query it for a passphrase. If there's no " dongsheng@627: "authentication agent running, or the agent doesn't store the necessary " dongsheng@627: "passphrase, you'll have to type your passphrase every time Mercurial tries to " dongsheng@627: "communicate with a server on your behalf (e.g. whenever you pull or push " dongsheng@627: "changes)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:658 dongsheng@627: msgid "" dongsheng@627: "The downside of storing passphrases in an agent is that it's possible for a " dongsheng@627: "well-prepared attacker to recover the plain text of your passphrases, in some " dongsheng@627: "cases even if your system has been power-cycled. You should make your own " dongsheng@627: "judgment as to whether this is an acceptable risk. It certainly saves a lot " dongsheng@627: "of repeated typing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:665 dongsheng@627: msgid "" dongsheng@627: "On Unix-like systems, the agent is called <command>ssh-agent</command>, and " dongsheng@627: "it's often run automatically for you when you log in. You'll need to use the " dongsheng@627: "<command>ssh-add</command> command to add passphrases to the agent's store. " dongsheng@627: "On Windows, if you're using PuTTY, the <command>pageant</command> command " dongsheng@627: "acts as the agent. It adds an icon to your system tray that will let you " dongsheng@627: "manage stored passphrases." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:676 dongsheng@627: msgid "Configuring the server side properly" dongsheng@630: msgstr "正确配置服务器端" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:678 dongsheng@627: msgid "" dongsheng@627: "Because ssh can be fiddly to set up if you're new to it, there's a variety of " dongsheng@627: "things that can go wrong. Add Mercurial on top, and there's plenty more " dongsheng@627: "scope for head-scratching. Most of these potential problems occur on the " dongsheng@627: "server side, not the client side. The good news is that once you've gotten a " dongsheng@627: "configuration working, it will usually continue to work indefinitely." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:686 dongsheng@627: msgid "" dongsheng@627: "Before you try using Mercurial to talk to an ssh server, it's best to make " dongsheng@627: "sure that you can use the normal <command>ssh</command> or <command>putty</" dongsheng@627: "command> command to talk to the server first. If you run into problems with " dongsheng@627: "using these commands directly, Mercurial surely won't work. Worse, it will " dongsheng@627: "obscure the underlying problem. Any time you want to debug ssh-related " dongsheng@627: "Mercurial problems, you should drop back to making sure that plain ssh client " dongsheng@627: "commands work first, <emphasis>before</emphasis> you worry about whether " dongsheng@627: "there's a problem with Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:697 dongsheng@627: msgid "" dongsheng@627: "The first thing to be sure of on the server side is that you can actually log " dongsheng@627: "in from another machine at all. If you can't use <command>ssh</command> or " dongsheng@627: "<command>putty</command> to log in, the error message you get may give you a " dongsheng@627: "few hints as to what's wrong. The most common problems are as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:704 dongsheng@627: msgid "" dongsheng@627: "If you get a <quote>connection refused</quote> error, either there isn't an " dongsheng@627: "SSH daemon running on the server at all, or it's inaccessible due to firewall " dongsheng@627: "configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:709 dongsheng@627: msgid "" dongsheng@627: "If you get a <quote>no route to host</quote> error, you either have an " dongsheng@627: "incorrect address for the server or a seriously locked down firewall that " dongsheng@627: "won't admit its existence at all." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:714 dongsheng@627: msgid "" dongsheng@627: "If you get a <quote>permission denied</quote> error, you may have mistyped " dongsheng@627: "the username on the server, or you could have mistyped your key's passphrase " dongsheng@627: "or the remote user's password." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:719 dongsheng@627: msgid "" dongsheng@627: "In summary, if you're having trouble talking to the server's ssh daemon, " dongsheng@627: "first make sure that one is running at all. On many systems it will be " dongsheng@627: "installed, but disabled, by default. Once you're done with this step, you " dongsheng@627: "should then check that the server's firewall is configured to allow incoming " dongsheng@627: "connections on the port the ssh daemon is listening on (usually 22). Don't " dongsheng@627: "worry about more exotic possibilities for misconfiguration until you've " dongsheng@627: "checked these two first." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:729 dongsheng@627: msgid "" dongsheng@627: "If you're using an authentication agent on the client side to store " dongsheng@627: "passphrases for your keys, you ought to be able to log into the server " dongsheng@627: "without being prompted for a passphrase or a password. If you're prompted " dongsheng@627: "for a passphrase, there are a few possible culprits." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:735 dongsheng@627: msgid "" dongsheng@627: "You might have forgotten to use <command>ssh-add</command> or " dongsheng@627: "<command>pageant</command> to store the passphrase." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:739 dongsheng@627: msgid "You might have stored the passphrase for the wrong key." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:742 dongsheng@627: msgid "" dongsheng@627: "If you're being prompted for the remote user's password, there are another " dongsheng@627: "few possible problems to check." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:745 dongsheng@627: msgid "" dongsheng@627: "Either the user's home directory or their <filename role=\"special\" class=" dongsheng@627: "\"directory\">.ssh</filename> directory might have excessively liberal " dongsheng@627: "permissions. As a result, the ssh daemon will not trust or read their " dongsheng@627: "<filename role=\"special\">authorized_keys</filename> file. For example, a " dongsheng@627: "group-writable home or <filename role=\"special\" class=\"directory\">.ssh</" dongsheng@627: "filename> directory will often cause this symptom." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:754 dongsheng@627: msgid "" dongsheng@627: "The user's <filename role=\"special\">authorized_keys</filename> file may " dongsheng@627: "have a problem. If anyone other than the user owns or can write to that file, " dongsheng@627: "the ssh daemon will not trust or read it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:761 dongsheng@627: msgid "" dongsheng@627: "In the ideal world, you should be able to run the following command " dongsheng@627: "successfully, and it should print exactly one line of output, the current " dongsheng@627: "date and time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:766 dongsheng@627: msgid "" dongsheng@627: "If, on your server, you have login scripts that print banners or other junk " dongsheng@627: "even when running non-interactive commands like this, you should fix them " dongsheng@627: "before you continue, so that they only print output if they're run " dongsheng@627: "interactively. Otherwise these banners will at least clutter up Mercurial's " dongsheng@627: "output. Worse, they could potentially cause problems with running Mercurial " dongsheng@627: "commands remotely. Mercurial makes tries to detect and ignore banners in non-" dongsheng@627: "interactive <command>ssh</command> sessions, but it is not foolproof. (If " dongsheng@627: "you're editing your login scripts on your server, the usual way to see if a " dongsheng@627: "login script is running in an interactive shell is to check the return code " dongsheng@627: "from the command <literal>tty -s</literal>.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:780 dongsheng@627: msgid "" dongsheng@627: "Once you've verified that plain old ssh is working with your server, the next " dongsheng@627: "step is to ensure that Mercurial runs on the server. The following command " dongsheng@627: "should run successfully:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:785 dongsheng@627: msgid "" dongsheng@627: "If you see an error message instead of normal <command role=\"hg-cmd\">hg " dongsheng@627: "version</command> output, this is usually because you haven't installed " dongsheng@627: "Mercurial to <filename class=\"directory\">/usr/bin</filename>. Don't worry " dongsheng@627: "if this is the case; you don't need to do that. But you should check for a " dongsheng@627: "few possible problems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:792 dongsheng@627: msgid "" dongsheng@627: "Is Mercurial really installed on the server at all? I know this sounds " dongsheng@627: "trivial, but it's worth checking!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:796 dongsheng@627: msgid "" dongsheng@627: "Maybe your shell's search path (usually set via the <envar>PATH</envar> " dongsheng@627: "environment variable) is simply misconfigured." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:800 dongsheng@627: msgid "" dongsheng@627: "Perhaps your <envar>PATH</envar> environment variable is only being set to " dongsheng@627: "point to the location of the <command>hg</command> executable if the login " dongsheng@627: "session is interactive. This can happen if you're setting the path in the " dongsheng@627: "wrong shell login script. See your shell's documentation for details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:807 dongsheng@627: msgid "" dongsheng@627: "The <envar>PYTHONPATH</envar> environment variable may need to contain the " dongsheng@627: "path to the Mercurial Python modules. It might not be set at all; it could " dongsheng@627: "be incorrect; or it may be set only if the login is interactive." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:814 dongsheng@627: msgid "" dongsheng@627: "If you can run <command role=\"hg-cmd\">hg version</command> over an ssh " dongsheng@627: "connection, well done! You've got the server and client sorted out. You " dongsheng@627: "should now be able to use Mercurial to access repositories hosted by that " dongsheng@627: "username on that server. If you run into problems with Mercurial and ssh at " dongsheng@627: "this point, try using the <option role=\"hg-opt-global\">--debug</option> " dongsheng@627: "option to get a clearer picture of what's going on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:824 dongsheng@627: msgid "Using compression with ssh" dongsheng@630: msgstr "通过 ssh 使用压缩" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:826 dongsheng@627: msgid "" dongsheng@627: "Mercurial does not compress data when it uses the ssh protocol, because the " dongsheng@627: "ssh protocol can transparently compress data. However, the default behaviour " dongsheng@627: "of ssh clients is <emphasis>not</emphasis> to request compression." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:831 dongsheng@627: msgid "" dongsheng@627: "Over any network other than a fast LAN (even a wireless network), using " dongsheng@627: "compression is likely to significantly speed up Mercurial's network " dongsheng@627: "operations. For example, over a WAN, someone measured compression as " dongsheng@627: "reducing the amount of time required to clone a particularly large repository " dongsheng@627: "from 51 minutes to 17 minutes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:838 dongsheng@627: msgid "" dongsheng@627: "Both <command>ssh</command> and <command>plink</command> accept a <option " dongsheng@627: "role=\"cmd-opt-ssh\">-C</option> option which turns on compression. You can " dongsheng@627: "easily edit your <filename role=\"special\"> /.hgrc</filename>\\ to enable " dongsheng@627: "compression for all of Mercurial's uses of the ssh protocol." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:845 dongsheng@627: msgid "" dongsheng@627: "If you use <command>ssh</command>, you can configure it to always use " dongsheng@627: "compression when talking to your server. To do this, edit your <filename " dongsheng@627: "role=\"special\">.ssh/config</filename> file (which may not yet exist), as " dongsheng@627: "follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:852 dongsheng@627: msgid "" dongsheng@627: "This defines an alias, <literal>hg</literal>. When you use it on the " dongsheng@627: "<command>ssh</command> command line or in a Mercurial <literal>ssh</literal>-" dongsheng@627: "protocol URL, it will cause <command>ssh</command> to connect to <literal>hg." dongsheng@627: "example.com</literal> and use compression. This gives you both a shorter " dongsheng@627: "name to type and compression, each of which is a good thing in its own right." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch06-collab.xml:863 dongsheng@627: msgid "Serving over HTTP using CGI" dongsheng@630: msgstr "使用 CGI 通过 HTTP 提供服务" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:865 dongsheng@627: msgid "" dongsheng@627: "Depending on how ambitious you are, configuring Mercurial's CGI interface can " dongsheng@627: "take anything from a few moments to several hours." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch06-collab.xml:869 dongsheng@627: msgid "" dongsheng@627: "We'll begin with the simplest of examples, and work our way towards a more " dongsheng@627: "complex configuration. Even for the most basic case, you're almost certainly " dongsheng@627: "going to need to read and modify your web server's configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch06-collab.xml:875 dongsheng@627: msgid "" dongsheng@627: "Configuring a web server is a complex, fiddly, and highly system-dependent " dongsheng@627: "activity. I can't possibly give you instructions that will cover anything " dongsheng@627: "like all of the cases you will encounter. Please use your discretion and " dongsheng@627: "judgment in following the sections below. Be prepared to make plenty of " dongsheng@627: "mistakes, and to spend a lot of time reading your server's error logs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:885 dongsheng@627: msgid "Web server configuration checklist" dongsheng@630: msgstr "Web 服务器配置检查表" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:887 dongsheng@627: msgid "" dongsheng@627: "Before you continue, do take a few moments to check a few aspects of your " dongsheng@627: "system's setup." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:891 dongsheng@627: msgid "" dongsheng@627: "Do you have a web server installed at all? Mac OS X ships with Apache, but " dongsheng@627: "many other systems may not have a web server installed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:895 dongsheng@627: msgid "" dongsheng@627: "If you have a web server installed, is it actually running? On most systems, " dongsheng@627: "even if one is present, it will be disabled by default." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:899 dongsheng@627: msgid "" dongsheng@627: "Is your server configured to allow you to run CGI programs in the directory " dongsheng@627: "where you plan to do so? Most servers default to explicitly disabling the " dongsheng@627: "ability to run CGI programs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:905 dongsheng@627: msgid "" dongsheng@627: "If you don't have a web server installed, and don't have substantial " dongsheng@627: "experience configuring Apache, you should consider using the " dongsheng@627: "<literal>lighttpd</literal> web server instead of Apache. Apache has a well-" dongsheng@627: "deserved reputation for baroque and confusing configuration. While " dongsheng@627: "<literal>lighttpd</literal> is less capable in some ways than Apache, most of " dongsheng@627: "these capabilities are not relevant to serving Mercurial repositories. And " dongsheng@627: "<literal>lighttpd</literal> is undeniably <emphasis>much</emphasis> easier to " dongsheng@627: "get started with than Apache." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:918 dongsheng@627: msgid "Basic CGI configuration" dongsheng@630: msgstr "基本 CGI 配置" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:920 dongsheng@627: msgid "" dongsheng@627: "On Unix-like systems, it's common for users to have a subdirectory named " dongsheng@627: "something like <filename class=\"directory\">public_html</filename> in their " dongsheng@627: "home directory, from which they can serve up web pages. A file named " dongsheng@627: "<filename>foo</filename> in this directory will be accessible at a URL of the " dongsheng@627: "form <literal>http://www.example.com/\\ {</literal>username/foo}." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:929 dongsheng@627: msgid "" dongsheng@627: "To get started, find the <filename role=\"special\">hgweb.cgi</filename> " dongsheng@627: "script that should be present in your Mercurial installation. If you can't " dongsheng@627: "quickly find a local copy on your system, simply download one from the master " dongsheng@627: "Mercurial repository at <ulink url=\"http://www.selenic.com/repo/hg/raw-file/" dongsheng@627: "tip/hgweb.cgi\">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:936 ../en/ch06-collab.xml:1109 dongsheng@627: msgid "" dongsheng@627: "You'll need to copy this script into your <filename class=\"directory" dongsheng@627: "\">public_html</filename> directory, and ensure that it's executable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:941 dongsheng@627: msgid "" dongsheng@627: "The <literal>755</literal> argument to <command>chmod</command> is a little " dongsheng@627: "more general than just making the script executable: it ensures that the " dongsheng@627: "script is executable by anyone, and that <quote>group</quote> and " dongsheng@627: "<quote>other</quote> write permissions are <emphasis>not</emphasis> set. If " dongsheng@627: "you were to leave those write permissions enabled, Apache's <literal>suexec</" dongsheng@627: "literal> subsystem would likely refuse to execute the script. In fact, " dongsheng@627: "<literal>suexec</literal> also insists that the <emphasis>directory</" dongsheng@627: "emphasis> in which the script resides must not be writable by others." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:955 dongsheng@627: msgid "What could <emphasis>possibly</emphasis> go wrong?" dongsheng@630: msgstr "什么<emphasis>可能</emphasis>会出错?" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:958 dongsheng@627: msgid "" dongsheng@627: "Once you've copied the CGI script into place, go into a web browser, and try " dongsheng@627: "to open the URL <ulink url=\"http://myhostname/ myuser/hgweb.cgi\">http://" dongsheng@627: "myhostname/ myuser/hgweb.cgi</ulink>, <emphasis>but</emphasis> brace yourself " dongsheng@627: "for instant failure. There's a high probability that trying to visit this " dongsheng@627: "URL will fail, and there are many possible reasons for this. In fact, you're " dongsheng@627: "likely to stumble over almost every one of the possible errors below, so " dongsheng@627: "please read carefully. The following are all of the problems I ran into on a " dongsheng@627: "system running Fedora 7, with a fresh installation of Apache, and a user " dongsheng@627: "account that I created specially to perform this exercise." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:972 dongsheng@627: msgid "" dongsheng@627: "Your web server may have per-user directories disabled. If you're using " dongsheng@627: "Apache, search your config file for a <literal>UserDir</literal> directive. " dongsheng@627: "If there's none present, per-user directories will be disabled. If one " dongsheng@627: "exists, but its value is <literal>disabled</literal>, then per-user " dongsheng@627: "directories will be disabled. Otherwise, the string after <literal>UserDir</" dongsheng@627: "literal> gives the name of the subdirectory that Apache will look in under " dongsheng@627: "your home directory, for example <filename class=\"directory\">public_html</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:983 dongsheng@627: msgid "" dongsheng@627: "Your file access permissions may be too restrictive. The web server must be " dongsheng@627: "able to traverse your home directory and directories under your <filename " dongsheng@627: "class=\"directory\">public_html</filename> directory, and read files under " dongsheng@627: "the latter too. Here's a quick recipe to help you to make your permissions " dongsheng@627: "more appropriate." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:993 dongsheng@627: msgid "" dongsheng@627: "The other possibility with permissions is that you might get a completely " dongsheng@627: "empty window when you try to load the script. In this case, it's likely that " dongsheng@627: "your access permissions are <emphasis>too permissive</emphasis>. Apache's " dongsheng@627: "<literal>suexec</literal> subsystem won't execute a script that's group- or " dongsheng@627: "world-writable, for example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1000 dongsheng@627: msgid "" dongsheng@627: "Your web server may be configured to disallow execution of CGI programs in " dongsheng@627: "your per-user web directory. Here's Apache's default per-user configuration " dongsheng@627: "from my Fedora system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1011 dongsheng@627: msgid "" dongsheng@627: "If you find a similar-looking <literal>Directory</literal> group in your " dongsheng@627: "Apache configuration, the directive to look at inside it is <literal>Options</" dongsheng@627: "literal>. Add <literal>ExecCGI</literal> to the end of this list if it's " dongsheng@627: "missing, and restart the web server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1018 dongsheng@627: msgid "" dongsheng@627: "If you find that Apache serves you the text of the CGI script instead of " dongsheng@627: "executing it, you may need to either uncomment (if already present) or add a " dongsheng@627: "directive like this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1024 dongsheng@627: msgid "" dongsheng@627: "The next possibility is that you might be served with a colourful Python " dongsheng@627: "backtrace claiming that it can't import a <literal>mercurial</literal>-" dongsheng@627: "related module. This is actually progress! The server is now capable of " dongsheng@627: "executing your CGI script. This error is only likely to occur if you're " dongsheng@627: "running a private installation of Mercurial, instead of a system-wide " dongsheng@627: "version. Remember that the web server runs the CGI program without any of " dongsheng@627: "the environment variables that you take for granted in an interactive " dongsheng@627: "session. If this error happens to you, edit your copy of <filename role=" dongsheng@627: "\"special\">hgweb.cgi</filename> and follow the directions inside it to " dongsheng@627: "correctly set your <envar>PYTHONPATH</envar> environment variable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1038 dongsheng@627: msgid "" dongsheng@627: "Finally, you are <emphasis>certain</emphasis> to by served with another " dongsheng@627: "colourful Python backtrace: this one will complain that it can't find " dongsheng@627: "<filename class=\"directory\">/path/to/repository</filename>. Edit your " dongsheng@627: "<filename role=\"special\">hgweb.cgi</filename> script and replace the " dongsheng@627: "<filename class=\"directory\">/path/to/repository</filename> string with the " dongsheng@627: "complete path to the repository you want to serve up." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1048 dongsheng@627: msgid "" dongsheng@627: "At this point, when you try to reload the page, you should be presented with " dongsheng@627: "a nice HTML view of your repository's history. Whew!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1054 dongsheng@627: msgid "Configuring lighttpd" dongsheng@630: msgstr "配置 lighttpd" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1056 dongsheng@627: msgid "" dongsheng@627: "To be exhaustive in my experiments, I tried configuring the increasingly " dongsheng@627: "popular <literal>lighttpd</literal> web server to serve the same repository " dongsheng@627: "as I described with Apache above. I had already overcome all of the problems " dongsheng@627: "I outlined with Apache, many of which are not server-specific. As a result, " dongsheng@627: "I was fairly sure that my file and directory permissions were good, and that " dongsheng@627: "my <filename role=\"special\">hgweb.cgi</filename> script was properly edited." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1066 dongsheng@627: msgid "" dongsheng@627: "Once I had Apache running, getting <literal>lighttpd</literal> to serve the " dongsheng@627: "repository was a snap (in other words, even if you're trying to use " dongsheng@627: "<literal>lighttpd</literal>, you should read the Apache section). I first " dongsheng@627: "had to edit the <literal>mod_access</literal> section of its config file to " dongsheng@627: "enable <literal>mod_cgi</literal> and <literal>mod_userdir</literal>, both of " dongsheng@627: "which were disabled by default on my system. I then added a few lines to the " dongsheng@627: "end of the config file, to configure these modules." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1078 dongsheng@627: msgid "" dongsheng@627: "With this done, <literal>lighttpd</literal> ran immediately for me. If I had " dongsheng@627: "configured <literal>lighttpd</literal> before Apache, I'd almost certainly " dongsheng@627: "have run into many of the same system-level configuration problems as I did " dongsheng@627: "with Apache. However, I found <literal>lighttpd</literal> to be noticeably " dongsheng@627: "easier to configure than Apache, even though I've used Apache for over a " dongsheng@627: "decade, and this was my first exposure to <literal>lighttpd</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:1091 dongsheng@627: msgid "Sharing multiple repositories with one CGI script" dongsheng@630: msgstr "使用一个 CGI 脚本共享多个版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1093 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">hgweb.cgi</filename> script only lets you " dongsheng@627: "publish a single repository, which is an annoying restriction. If you want " dongsheng@627: "to publish more than one without wracking yourself with multiple copies of " dongsheng@627: "the same script, each with different names, a better choice is to use the " dongsheng@627: "<filename role=\"special\">hgwebdir.cgi</filename> script." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1101 dongsheng@627: msgid "" dongsheng@627: "The procedure to configure <filename role=\"special\">hgwebdir.cgi</filename> " dongsheng@627: "is only a little more involved than for <filename role=\"special\">hgweb.cgi</" dongsheng@627: "filename>. First, you must obtain a copy of the script. If you don't have " dongsheng@627: "one handy, you can download a copy from the master Mercurial repository at " dongsheng@627: "<ulink url=\"http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi" dongsheng@627: "\">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1114 dongsheng@627: msgid "" dongsheng@627: "With basic configuration out of the way, try to visit <ulink url=\"http://" dongsheng@627: "myhostname/ myuser/hgwebdir.cgi\">http://myhostname/ myuser/hgwebdir.cgi</" dongsheng@627: "ulink> in your browser. It should display an empty list of repositories. If " dongsheng@627: "you get a blank window or error message, try walking through the list of " dongsheng@627: "potential problems in section <xref linkend=\"sec.collab.wtf\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1123 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">hgwebdir.cgi</filename> script relies on an " dongsheng@627: "external configuration file. By default, it searches for a file named " dongsheng@627: "<filename role=\"special\">hgweb.config</filename> in the same directory as " dongsheng@627: "itself. You'll need to create this file, and make it world-readable. The " dongsheng@627: "format of the file is similar to a Windows <quote>ini</quote> file, as " dongsheng@627: "understood by Python's <literal>ConfigParser</literal> <citation>web:" dongsheng@627: "configparser</citation> module." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1133 dongsheng@627: msgid "" dongsheng@627: "The easiest way to configure <filename role=\"special\">hgwebdir.cgi</" dongsheng@627: "filename> is with a section named <literal>collections</literal>. This will " dongsheng@627: "automatically publish <emphasis>every</emphasis> repository under the " dongsheng@627: "directories you name. The section should look like this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1141 dongsheng@627: msgid "" dongsheng@627: "Mercurial interprets this by looking at the directory name on the " dongsheng@627: "<emphasis>right</emphasis> hand side of the <quote><literal>=</literal></" dongsheng@627: "quote> sign; finding repositories in that directory hierarchy; and using the " dongsheng@627: "text on the <emphasis>left</emphasis> to strip off matching text from the " dongsheng@627: "names it will actually list in the web interface. The remaining component of " dongsheng@627: "a path after this stripping has occurred is called a <quote>virtual path</" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1150 dongsheng@627: msgid "" dongsheng@627: "Given the example above, if we have a repository whose local path is " dongsheng@627: "<filename class=\"directory\">/my/root/this/repo</filename>, the CGI script " dongsheng@627: "will strip the leading <filename class=\"directory\">/my/root</filename> from " dongsheng@627: "the name, and publish the repository with a virtual path of <filename class=" dongsheng@627: "\"directory\">this/repo</filename>. If the base URL for our CGI script is " dongsheng@627: "<ulink url=\"http://myhostname/ myuser/hgwebdir.cgi\">http://myhostname/ " dongsheng@627: "myuser/hgwebdir.cgi</ulink>, the complete URL for that repository will be " dongsheng@627: "<ulink url=\"http://myhostname/ myuser/hgwebdir.cgi/this/repo\">http://" dongsheng@627: "myhostname/ myuser/hgwebdir.cgi/this/repo</ulink>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1164 dongsheng@627: msgid "" dongsheng@627: "If we replace <filename class=\"directory\">/my/root</filename> on the left " dongsheng@627: "hand side of this example with <filename class=\"directory\">/my</filename>, " dongsheng@627: "then <filename role=\"special\">hgwebdir.cgi</filename> will only strip off " dongsheng@627: "<filename class=\"directory\">/my</filename> from the repository name, and " dongsheng@627: "will give us a virtual path of <filename class=\"directory\">root/this/repo</" dongsheng@627: "filename> instead of <filename class=\"directory\">this/repo</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1174 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\">hgwebdir.cgi</filename> script will " dongsheng@627: "recursively search each directory listed in the <literal>collections</" dongsheng@627: "literal> section of its configuration file, but it will <literal>not</" dongsheng@627: "literal> recurse into the repositories it finds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1180 dongsheng@627: msgid "" dongsheng@627: "The <literal>collections</literal> mechanism makes it easy to publish many " dongsheng@627: "repositories in a <quote>fire and forget</quote> manner. You only need to " dongsheng@627: "set up the CGI script and configuration file one time. Afterwards, you can " dongsheng@627: "publish or unpublish a repository at any time by simply moving it into, or " dongsheng@627: "out of, the directory hierarchy in which you've configured <filename role=" dongsheng@627: "\"special\">hgwebdir.cgi</filename> to look." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1190 dongsheng@627: msgid "Explicitly specifying which repositories to publish" dongsheng@630: msgstr "明确指出要发布的版本库" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1193 dongsheng@627: msgid "" dongsheng@627: "In addition to the <literal>collections</literal> mechanism, the <filename " dongsheng@627: "role=\"special\">hgwebdir.cgi</filename> script allows you to publish a " dongsheng@627: "specific list of repositories. To do so, create a <literal>paths</literal> " dongsheng@627: "section, with contents of the following form." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1201 dongsheng@627: msgid "" dongsheng@627: "In this case, the virtual path (the component that will appear in a URL) is " dongsheng@627: "on the left hand side of each definition, while the path to the repository is " dongsheng@627: "on the right. Notice that there does not need to be any relationship between " dongsheng@627: "the virtual path you choose and the location of a repository in your " dongsheng@627: "filesystem." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1208 dongsheng@627: msgid "" dongsheng@627: "If you wish, you can use both the <literal>collections</literal> and " dongsheng@627: "<literal>paths</literal> mechanisms simultaneously in a single configuration " dongsheng@627: "file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><note><para> dongsheng@627: #: ../en/ch06-collab.xml:1214 dongsheng@627: msgid "" dongsheng@627: "If multiple repositories have the same virtual path, <filename role=\"special" dongsheng@627: "\">hgwebdir.cgi</filename> will not report an error. Instead, it will behave " dongsheng@627: "unpredictably." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:1223 dongsheng@627: msgid "Downloading source archives" dongsheng@630: msgstr "下载源代码档案包" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1225 dongsheng@627: msgid "" dongsheng@627: "Mercurial's web interface lets users download an archive of any revision. " dongsheng@627: "This archive will contain a snapshot of the working directory as of that " dongsheng@627: "revision, but it will not contain a copy of the repository data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1230 dongsheng@627: msgid "" dongsheng@627: "By default, this feature is not enabled. To enable it, you'll need to add an " dongsheng@627: "<envar role=\"rc-item-web\">allow_archive</envar> item to the <literal role=" dongsheng@627: "\"rc-web\">web</literal> section of your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch06-collab.xml:1238 dongsheng@627: msgid "Web configuration options" dongsheng@630: msgstr "Web 配置选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1240 dongsheng@627: msgid "" dongsheng@627: "Mercurial's web interfaces (the <command role=\"hg-cmd\">hg serve</command> " dongsheng@627: "command, and the <filename role=\"special\">hgweb.cgi</filename> and " dongsheng@627: "<filename role=\"special\">hgwebdir.cgi</filename> scripts) have a number of " dongsheng@627: "configuration options that you can set. These belong in a section named " dongsheng@627: "<literal role=\"rc-web\">web</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1248 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">allow_archive</envar>: Determines which (if any) " dongsheng@627: "archive download mechanisms Mercurial supports. If you enable this feature, " dongsheng@627: "users of the web interface will be able to download an archive of whatever " dongsheng@627: "revision of a repository they are viewing. To enable the archive feature, " dongsheng@627: "this item must take the form of a sequence of words drawn from the list below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1257 dongsheng@627: msgid "" dongsheng@627: "<literal>bz2</literal>: A <command>tar</command> archive, compressed using " dongsheng@627: "<literal>bzip2</literal> compression. This has the best compression ratio, " dongsheng@627: "but uses the most CPU time on the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1263 dongsheng@627: msgid "" dongsheng@627: "<literal>gz</literal>: A <command>tar</command> archive, compressed using " dongsheng@627: "<literal>gzip</literal> compression." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1267 dongsheng@627: msgid "" dongsheng@627: "<literal>zip</literal>: A <command>zip</command> archive, compressed using " dongsheng@627: "LZW compression. This format has the worst compression ratio, but is widely " dongsheng@627: "used in the Windows world." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1273 dongsheng@627: msgid "" dongsheng@627: "If you provide an empty list, or don't have an <envar role=\"rc-item-web" dongsheng@627: "\">allow_archive</envar> entry at all, this feature will be disabled. Here " dongsheng@627: "is an example of how to enable all three supported formats." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1280 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">allowpull</envar>: Boolean. Determines whether " dongsheng@627: "the web interface allows remote users to <command role=\"hg-cmd\">hg pull</" dongsheng@627: "command> and <command role=\"hg-cmd\">hg clone</command> this repository over " dongsheng@627: "HTTP. If set to <literal>no</literal> or <literal>false</literal>, only the " dongsheng@627: "<quote>human-oriented</quote> portion of the web interface is available." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1289 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">contact</envar>: String. A free-form (but " dongsheng@627: "preferably brief) string identifying the person or group in charge of the " dongsheng@627: "repository. This often contains the name and email address of a person or " dongsheng@627: "mailing list. It often makes sense to place this entry in a repository's own " dongsheng@627: "<filename role=\"special\">.hg/hgrc</filename> file, but it can make sense to " dongsheng@627: "use in a global <filename role=\"special\"> /.hgrc</filename>\\ if every " dongsheng@627: "repository has a single maintainer." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1300 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">maxchanges</envar>: Integer. The default maximum " dongsheng@627: "number of changesets to display in a single page of output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1304 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">maxfiles</envar>: Integer. The default maximum " dongsheng@627: "number of modified files to display in a single page of output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1308 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">stripes</envar>: Integer. If the web interface " dongsheng@627: "displays alternating <quote>stripes</quote> to make it easier to visually " dongsheng@627: "align rows when you are looking at a table, this number controls the number " dongsheng@627: "of rows in each stripe." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1314 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">style</envar>: Controls the template Mercurial " dongsheng@627: "uses to display the web interface. Mercurial ships with two web templates, " dongsheng@627: "named <literal>default</literal> and <literal>gitweb</literal> (the latter is " dongsheng@627: "much more visually attractive). You can also specify a custom template of " dongsheng@627: "your own; see chapter <xref linkend=\"chap.template\"/> for details. Here, " dongsheng@627: "you can see how to enable the <literal>gitweb</literal> style." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1325 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">templates</envar>: Path. The directory in which " dongsheng@627: "to search for template files. By default, Mercurial searches in the " dongsheng@627: "directory in which it was installed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch06-collab.xml:1330 dongsheng@627: msgid "" dongsheng@627: "If you are using <filename role=\"special\">hgwebdir.cgi</filename>, you can " dongsheng@627: "place a few configuration items in a <literal role=\"rc-web\">web</literal> " dongsheng@627: "section of the <filename role=\"special\">hgweb.config</filename> file " dongsheng@627: "instead of a <filename role=\"special\"> /.hgrc</filename>\\ file, for " dongsheng@627: "convenience. These items are <envar role=\"rc-item-web\">motd</envar> and " dongsheng@627: "<envar role=\"rc-item-web\">style</envar>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1341 dongsheng@627: msgid "Options specific to an individual repository" dongsheng@630: msgstr "针对单个版本库的选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1343 dongsheng@627: msgid "" dongsheng@627: "A few <literal role=\"rc-web\">web</literal> configuration items ought to be " dongsheng@627: "placed in a repository's local <filename role=\"special\">.hg/hgrc</" dongsheng@627: "filename>, rather than a user's or global <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1349 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">description</envar>: String. A free-form (but " dongsheng@627: "preferably brief) string that describes the contents or purpose of the " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1354 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">name</envar>: String. The name to use for the " dongsheng@627: "repository in the web interface. This overrides the default name, which is " dongsheng@627: "the last component of the repository's path." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1362 dongsheng@627: msgid "" dongsheng@627: "Options specific to the <command role=\"hg-cmd\">hg serve</command> command" dongsheng@630: msgstr "命令 <command role=\"hg-cmd\">hg serve</command> 的选项" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1365 dongsheng@627: msgid "" dongsheng@627: "Some of the items in the <literal role=\"rc-web\">web</literal> section of a " dongsheng@627: "<filename role=\"special\"> /.hgrc</filename>\\ file are only for use with " dongsheng@627: "the <command role=\"hg-cmd\">hg serve</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1371 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">accesslog</envar>: Path. The name of a file into " dongsheng@627: "which to write an access log. By default, the <command role=\"hg-cmd\">hg " dongsheng@627: "serve</command> command writes this information to standard output, not to a " dongsheng@627: "file. Log entries are written in the standard <quote>combined</quote> file " dongsheng@627: "format used by almost all web servers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1379 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">address</envar>: String. The local address on " dongsheng@627: "which the server should listen for incoming connections. By default, the " dongsheng@627: "server listens on all addresses." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1384 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">errorlog</envar>: Path. The name of a file into " dongsheng@627: "which to write an error log. By default, the <command role=\"hg-cmd\">hg " dongsheng@627: "serve</command> command writes this information to standard error, not to a " dongsheng@627: "file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1390 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">ipv6</envar>: Boolean. Whether to use the IPv6 " dongsheng@627: "protocol. By default, IPv6 is not used." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch06-collab.xml:1394 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-web\">port</envar>: Integer. The TCP port number on " dongsheng@627: "which the server should listen. The default port number used is 8000." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch06-collab.xml:1401 dongsheng@627: msgid "" dongsheng@627: "Choosing the right <filename role=\"special\"> /.hgrc</filename>\\ file to " dongsheng@627: "add <literal role=\"rc-web\">web</literal> items to" dongsheng@627: msgstr "" dongsheng@630: "选择正确的 <filename role=\"special\"> /.hgrc</filename> 文件增加到 <literal " dongsheng@630: "role=\"rc-web\">web</literal> 条目" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1405 dongsheng@627: msgid "" dongsheng@627: "It is important to remember that a web server like Apache or " dongsheng@627: "<literal>lighttpd</literal> will run under a user ID that is different to " dongsheng@627: "yours. CGI scripts run by your server, such as <filename role=\"special" dongsheng@627: "\">hgweb.cgi</filename>, will usually also run under that user ID." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch06-collab.xml:1412 dongsheng@627: msgid "" dongsheng@627: "If you add <literal role=\"rc-web\">web</literal> items to your own personal " dongsheng@627: "<filename role=\"special\"> /.hgrc</filename>\\ file, CGI scripts won't read " dongsheng@627: "that <filename role=\"special\"> /.hgrc</filename>\\ file. Those settings " dongsheng@627: "will thus only affect the behaviour of the <command role=\"hg-cmd\">hg serve</" dongsheng@627: "command> command when you run it. To cause CGI scripts to see your settings, " dongsheng@627: "either create a <filename role=\"special\"> /.hgrc</filename>\\ file in the " dongsheng@627: "home directory of the user ID that runs your web server, or add those " dongsheng@627: "settings to a system-wide <filename role=\"special\"> /.hgrc</filename>\\ " dongsheng@627: "file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch07-filenames.xml:5 dongsheng@627: msgid "File names and pattern matching" dongsheng@627: msgstr "文件名称与模式匹配" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch07-filenames.xml:7 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides mechanisms that let you work with file names in a " dongsheng@627: "consistent and expressive way." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:11 dongsheng@627: msgid "Simple file naming" dongsheng@630: msgstr "简单文件名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:13 dongsheng@627: msgid "" dongsheng@627: "Mercurial uses a unified piece of machinery <quote>under the hood</quote> to " dongsheng@627: "handle file names. Every command behaves uniformly with respect to file " dongsheng@627: "names. The way in which commands work with file names is as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:18 dongsheng@627: msgid "" dongsheng@627: "If you explicitly name real files on the command line, Mercurial works with " dongsheng@627: "exactly those files, as you would expect. &interaction.filenames.files;" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:22 dongsheng@627: msgid "" dongsheng@627: "When you provide a directory name, Mercurial will interpret this as " dongsheng@627: "<quote>operate on every file in this directory and its subdirectories</" dongsheng@627: "quote>. Mercurial traverses the files and subdirectories in a directory in " dongsheng@627: "alphabetical order. When it encounters a subdirectory, it will traverse that " dongsheng@627: "subdirectory before continuing with the current directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:33 dongsheng@627: msgid "Running commands without any file names" dongsheng@630: msgstr "不提供文件名称的执行命令" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:35 dongsheng@627: msgid "" dongsheng@627: "Mercurial's commands that work with file names have useful default behaviours " dongsheng@627: "when you invoke them without providing any file names or patterns. What kind " dongsheng@627: "of behaviour you should expect depends on what the command does. Here are a " dongsheng@627: "few rules of thumb you can use to predict what a command is likely to do if " dongsheng@627: "you don't give it any names to work with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:42 dongsheng@627: msgid "" dongsheng@627: "Most commands will operate on the entire working directory. This is what the " dongsheng@627: "<command role=\"hg-cmd\">hg add</command> command does, for example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:46 dongsheng@627: msgid "" dongsheng@627: "If the command has effects that are difficult or impossible to reverse, it " dongsheng@627: "will force you to explicitly provide at least one name or pattern (see " dongsheng@627: "below). This protects you from accidentally deleting files by running " dongsheng@627: "<command role=\"hg-cmd\">hg remove</command> with no arguments, for example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:54 dongsheng@627: msgid "" dongsheng@627: "It's easy to work around these default behaviours if they don't suit you. If " dongsheng@627: "a command normally operates on the whole working directory, you can invoke it " dongsheng@627: "on just the current directory and its subdirectories by giving it the name " dongsheng@627: "<quote><filename class=\"directory\">.</filename></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:62 dongsheng@627: msgid "" dongsheng@627: "Along the same lines, some commands normally print file names relative to the " dongsheng@627: "root of the repository, even if you're invoking them from a subdirectory. " dongsheng@627: "Such a command will print file names relative to your subdirectory if you " dongsheng@627: "give it explicit names. Here, we're going to run <command role=\"hg-cmd\">hg " dongsheng@627: "status</command> from a subdirectory, and get it to operate on the entire " dongsheng@627: "working directory while printing file names relative to our subdirectory, by " dongsheng@627: "passing it the output of the <command role=\"hg-cmd\">hg root</command> " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:76 dongsheng@627: msgid "Telling you what's going on" dongsheng@630: msgstr "告诉你正在做什么" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:78 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg add</command> example in the preceding " dongsheng@627: "section illustrates something else that's helpful about Mercurial commands. " dongsheng@627: "If a command operates on a file that you didn't name explicitly on the " dongsheng@627: "command line, it will usually print the name of the file, so that you will " dongsheng@627: "not be surprised what's going on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:85 dongsheng@627: msgid "" dongsheng@627: "The principle here is of <emphasis>least surprise</emphasis>. If you've " dongsheng@627: "exactly named a file on the command line, there's no point in repeating it " dongsheng@627: "back at you. If Mercurial is acting on a file <emphasis>implicitly</" dongsheng@627: "emphasis>, because you provided no names, or a directory, or a pattern (see " dongsheng@627: "below), it's safest to tell you what it's doing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:92 dongsheng@627: msgid "" dongsheng@627: "For commands that behave this way, you can silence them using the <option " dongsheng@627: "role=\"hg-opt-global\">-q</option> option. You can also get them to print " dongsheng@627: "the name of every file, even those you've named explicitly, using the <option " dongsheng@627: "role=\"hg-opt-global\">-v</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:100 dongsheng@627: msgid "Using patterns to identify files" dongsheng@630: msgstr "使用模式标识文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:102 dongsheng@627: msgid "" dongsheng@627: "In addition to working with file and directory names, Mercurial lets you use " dongsheng@627: "<emphasis>patterns</emphasis> to identify files. Mercurial's pattern " dongsheng@627: "handling is expressive." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:106 dongsheng@627: msgid "" dongsheng@627: "On Unix-like systems (Linux, MacOS, etc.), the job of matching file names to " dongsheng@627: "patterns normally falls to the shell. On these systems, you must explicitly " dongsheng@627: "tell Mercurial that a name is a pattern. On Windows, the shell does not " dongsheng@627: "expand patterns, so Mercurial will automatically identify names that are " dongsheng@627: "patterns, and expand them for you." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:113 dongsheng@627: msgid "" dongsheng@627: "To provide a pattern in place of a regular name on the command line, the " dongsheng@627: "mechanism is simple:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:116 dongsheng@627: msgid "" dongsheng@627: "That is, a pattern is identified by a short text string that says what kind " dongsheng@627: "of pattern this is, followed by a colon, followed by the actual pattern." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:120 dongsheng@627: msgid "" dongsheng@627: "Mercurial supports two kinds of pattern syntax. The most frequently used is " dongsheng@627: "called <literal>glob</literal>; this is the same kind of pattern matching " dongsheng@627: "used by the Unix shell, and should be familiar to Windows command prompt " dongsheng@627: "users, too." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:125 dongsheng@627: msgid "" dongsheng@627: "When Mercurial does automatic pattern matching on Windows, it uses " dongsheng@627: "<literal>glob</literal> syntax. You can thus omit the <quote><literal>glob:</" dongsheng@627: "literal></quote> prefix on Windows, but it's safe to use it, too." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:130 dongsheng@627: msgid "" dongsheng@627: "The <literal>re</literal> syntax is more powerful; it lets you specify " dongsheng@627: "patterns using regular expressions, also known as regexps." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:134 dongsheng@627: msgid "" dongsheng@627: "By the way, in the examples that follow, notice that I'm careful to wrap all " dongsheng@627: "of my patterns in quote characters, so that they won't get expanded by the " dongsheng@627: "shell before Mercurial sees them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:140 dongsheng@627: msgid "Shell-style <literal>glob</literal> patterns" dongsheng@630: msgstr "外壳风格的 <literal>glob</literal> 模式" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:142 dongsheng@627: msgid "" dongsheng@627: "This is an overview of the kinds of patterns you can use when you're matching " dongsheng@627: "on glob patterns." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:145 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>*</literal></quote> character matches any string, within " dongsheng@627: "a single directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:150 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>**</literal></quote> pattern matches any string, and " dongsheng@627: "crosses directory boundaries. It's not a standard Unix glob token, but it's " dongsheng@627: "accepted by several popular Unix shells, and is very useful." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:157 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>?</literal></quote> pattern matches any single character." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:162 dongsheng@627: msgid "" dongsheng@627: "The <quote><literal>[</literal></quote> character begins a " dongsheng@627: "<emphasis>character class</emphasis>. This matches any single character " dongsheng@627: "within the class. The class ends with a <quote><literal>]</literal></quote> " dongsheng@627: "character. A class may contain multiple <emphasis>range</emphasis>s of the " dongsheng@627: "form <quote><literal>a-f</literal></quote>, which is shorthand for " dongsheng@627: "<quote><literal>abcdef</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:172 dongsheng@627: msgid "" dongsheng@627: "If the first character after the <quote><literal>[</literal></quote> in a " dongsheng@627: "character class is a <quote><literal>!</literal></quote>, it " dongsheng@627: "<emphasis>negates</emphasis> the class, making it match any single character " dongsheng@627: "not in the class." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:178 dongsheng@627: msgid "" dongsheng@627: "A <quote><literal>{</literal></quote> begins a group of subpatterns, where " dongsheng@627: "the whole group matches if any subpattern in the group matches. The " dongsheng@627: "<quote><literal>,</literal></quote> character separates subpatterns, and " dongsheng@627: "<quote><literal>}</literal></quote> ends the group." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch07-filenames.xml:187 dongsheng@627: msgid "Watch out!" dongsheng@630: msgstr "千万小心！" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch07-filenames.xml:189 dongsheng@627: msgid "" dongsheng@627: "Don't forget that if you want to match a pattern in any directory, you should " dongsheng@627: "not be using the <quote><literal>*</literal></quote> match-any token, as this " dongsheng@627: "will only match within one directory. Instead, use the <quote><literal>**</" dongsheng@627: "literal></quote> token. This small example illustrates the difference " dongsheng@627: "between the two." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:201 dongsheng@627: msgid "Regular expression matching with <literal>re</literal> patterns" dongsheng@630: msgstr "使用 <literal>re</literal> 模式的正则表达式匹配" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:204 dongsheng@627: msgid "" dongsheng@627: "Mercurial accepts the same regular expression syntax as the Python " dongsheng@627: "programming language (it uses Python's regexp engine internally). This is " dongsheng@627: "based on the Perl language's regexp syntax, which is the most popular dialect " dongsheng@627: "in use (it's also used in Java, for example)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:210 dongsheng@627: msgid "" dongsheng@627: "I won't discuss Mercurial's regexp dialect in any detail here, as regexps are " dongsheng@627: "not often used. Perl-style regexps are in any case already exhaustively " dongsheng@627: "documented on a multitude of web sites, and in many books. Instead, I will " dongsheng@627: "focus here on a few things you should know if you find yourself needing to " dongsheng@627: "use regexps with Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:217 dongsheng@627: msgid "" dongsheng@627: "A regexp is matched against an entire file name, relative to the root of the " dongsheng@627: "repository. In other words, even if you're already in subbdirectory " dongsheng@627: "<filename class=\"directory\">foo</filename>, if you want to match files " dongsheng@627: "under this directory, your pattern must start with <quote><literal>foo/</" dongsheng@627: "literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:224 dongsheng@627: msgid "" dongsheng@627: "One thing to note, if you're familiar with Perl-style regexps, is that " dongsheng@627: "Mercurial's are <emphasis>rooted</emphasis>. That is, a regexp starts " dongsheng@627: "matching against the beginning of a string; it doesn't look for a match " dongsheng@627: "anywhere within the string. To match anywhere in a string, start your " dongsheng@627: "pattern with <quote><literal>.*</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:234 dongsheng@627: msgid "Filtering files" dongsheng@630: msgstr "过滤文件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:236 dongsheng@627: msgid "" dongsheng@627: "Not only does Mercurial give you a variety of ways to specify files; it lets " dongsheng@627: "you further winnow those files using <emphasis>filters</emphasis>. Commands " dongsheng@627: "that work with file names accept two filtering options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:241 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-opt-global\">-I</option>, or <option role=\"hg-opt-global" dongsheng@627: "\">--include</option>, lets you specify a pattern that file names must match " dongsheng@627: "in order to be processed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:246 dongsheng@627: msgid "" dongsheng@627: "<option role=\"hg-opt-global\">-X</option>, or <option role=\"hg-opt-global" dongsheng@627: "\">--exclude</option>, gives you a way to <emphasis>avoid</emphasis> " dongsheng@627: "processing files, if they match this pattern." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:251 dongsheng@627: msgid "" dongsheng@627: "You can provide multiple <option role=\"hg-opt-global\">-I</option> and " dongsheng@627: "<option role=\"hg-opt-global\">-X</option> options on the command line, and " dongsheng@627: "intermix them as you please. Mercurial interprets the patterns you provide " dongsheng@627: "using glob syntax by default (but you can use regexps if you need to)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:258 dongsheng@627: msgid "" dongsheng@627: "You can read a <option role=\"hg-opt-global\">-I</option> filter as " dongsheng@627: "<quote>process only the files that match this filter</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:264 dongsheng@627: msgid "" dongsheng@627: "The <option role=\"hg-opt-global\">-X</option> filter is best read as " dongsheng@627: "<quote>process only the files that don't match this pattern</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:272 dongsheng@627: msgid "Ignoring unwanted files and directories" dongsheng@630: msgstr "忽略不需要的文件和目录" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:274 dongsheng@627: msgid "XXX." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch07-filenames.xml:278 dongsheng@627: msgid "Case sensitivity" dongsheng@630: msgstr "大小写敏感性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:280 dongsheng@627: msgid "" dongsheng@627: "If you're working in a mixed development environment that contains both Linux " dongsheng@627: "(or other Unix) systems and Macs or Windows systems, you should keep in the " dongsheng@627: "back of your mind the knowledge that they treat the case (<quote>N</quote> " dongsheng@627: "versus <quote>n</quote>) of file names in incompatible ways. This is not " dongsheng@627: "very likely to affect you, and it's easy to deal with if it does, but it " dongsheng@627: "could surprise you if you don't know about it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:289 dongsheng@627: msgid "" dongsheng@627: "Operating systems and filesystems differ in the way they handle the " dongsheng@627: "<emphasis>case</emphasis> of characters in file and directory names. There " dongsheng@627: "are three common ways to handle case in names." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:294 dongsheng@627: msgid "" dongsheng@627: "Completely case insensitive. Uppercase and lowercase versions of a letter " dongsheng@627: "are treated as identical, both when creating a file and during subsequent " dongsheng@627: "accesses. This is common on older DOS-based systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:299 dongsheng@627: msgid "" dongsheng@627: "Case preserving, but insensitive. When a file or directory is created, the " dongsheng@627: "case of its name is stored, and can be retrieved and displayed by the " dongsheng@627: "operating system. When an existing file is being looked up, its case is " dongsheng@627: "ignored. This is the standard arrangement on Windows and MacOS. The names " dongsheng@627: "<filename>foo</filename> and <filename>FoO</filename> identify the same " dongsheng@627: "file. This treatment of uppercase and lowercase letters as interchangeable " dongsheng@627: "is also referred to as <emphasis>case folding</emphasis>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch07-filenames.xml:310 dongsheng@627: msgid "" dongsheng@627: "Case sensitive. The case of a name is significant at all times. The names " dongsheng@627: "<filename>foo</filename> and {FoO} identify different files. This is the way " dongsheng@627: "Linux and Unix systems normally work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch07-filenames.xml:316 dongsheng@627: msgid "" dongsheng@627: "On Unix-like systems, it is possible to have any or all of the above ways of " dongsheng@627: "handling case in action at once. For example, if you use a USB thumb drive " dongsheng@627: "formatted with a FAT32 filesystem on a Linux system, Linux will handle names " dongsheng@627: "on that filesystem in a case preserving, but insensitive, way." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:323 dongsheng@627: msgid "Safe, portable repository storage" dongsheng@630: msgstr "安全，可移植的版本库存储" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:325 dongsheng@627: msgid "" dongsheng@627: "Mercurial's repository storage mechanism is <emphasis>case safe</emphasis>. " dongsheng@627: "It translates file names so that they can be safely stored on both case " dongsheng@627: "sensitive and case insensitive filesystems. This means that you can use " dongsheng@627: "normal file copying tools to transfer a Mercurial repository onto, for " dongsheng@627: "example, a USB thumb drive, and safely move that drive and repository back " dongsheng@627: "and forth between a Mac, a PC running Windows, and a Linux box." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:336 dongsheng@627: msgid "Detecting case conflicts" dongsheng@630: msgstr "检测大小写冲突" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:338 dongsheng@627: msgid "" dongsheng@627: "When operating in the working directory, Mercurial honours the naming policy " dongsheng@627: "of the filesystem where the working directory is located. If the filesystem " dongsheng@627: "is case preserving, but insensitive, Mercurial will treat names that differ " dongsheng@627: "only in case as the same." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:344 dongsheng@627: msgid "" dongsheng@627: "An important aspect of this approach is that it is possible to commit a " dongsheng@627: "changeset on a case sensitive (typically Linux or Unix) filesystem that will " dongsheng@627: "cause trouble for users on case insensitive (usually Windows and MacOS) " dongsheng@627: "users. If a Linux user commits changes to two files, one named " dongsheng@627: "<filename>myfile.c</filename> and the other named <filename>MyFile.C</" dongsheng@627: "filename>, they will be stored correctly in the repository. And in the " dongsheng@627: "working directories of other Linux users, they will be correctly represented " dongsheng@627: "as separate files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:355 dongsheng@627: msgid "" dongsheng@627: "If a Windows or Mac user pulls this change, they will not initially have a " dongsheng@627: "problem, because Mercurial's repository storage mechanism is case safe. " dongsheng@627: "However, once they try to <command role=\"hg-cmd\">hg update</command> the " dongsheng@627: "working directory to that changeset, or <command role=\"hg-cmd\">hg merge</" dongsheng@627: "command> with that changeset, Mercurial will spot the conflict between the " dongsheng@627: "two file names that the filesystem would treat as the same, and forbid the " dongsheng@627: "update or merge from occurring." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch07-filenames.xml:367 dongsheng@627: msgid "Fixing a case conflict" dongsheng@630: msgstr "修正大小写冲突" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:369 dongsheng@627: msgid "" dongsheng@627: "If you are using Windows or a Mac in a mixed environment where some of your " dongsheng@627: "collaborators are using Linux or Unix, and Mercurial reports a case folding " dongsheng@627: "conflict when you try to <command role=\"hg-cmd\">hg update</command> or " dongsheng@627: "<command role=\"hg-cmd\">hg merge</command>, the procedure to fix the problem " dongsheng@627: "is simple." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:376 dongsheng@627: msgid "" dongsheng@627: "Just find a nearby Linux or Unix box, clone the problem repository onto it, " dongsheng@627: "and use Mercurial's <command role=\"hg-cmd\">hg rename</command> command to " dongsheng@627: "change the names of any offending files or directories so that they will no " dongsheng@627: "longer cause case folding conflicts. Commit this change, <command role=\"hg-" dongsheng@627: "cmd\">hg pull</command> or <command role=\"hg-cmd\">hg push</command> it " dongsheng@627: "across to your Windows or MacOS system, and <command role=\"hg-cmd\">hg " dongsheng@627: "update</command> to the revision with the non-conflicting names." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch07-filenames.xml:386 dongsheng@627: msgid "" dongsheng@627: "The changeset with case-conflicting names will remain in your project's " dongsheng@627: "history, and you still won't be able to <command role=\"hg-cmd\">hg update</" dongsheng@627: "command> your working directory to that changeset on a Windows or MacOS " dongsheng@627: "system, but you can continue development unimpeded." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch07-filenames.xml:393 dongsheng@627: msgid "" dongsheng@627: "Prior to version 0.9.3, Mercurial did not use a case safe repository storage " dongsheng@627: "mechanism, and did not detect case folding conflicts. If you are using an " dongsheng@627: "older version of Mercurial on Windows or MacOS, I strongly recommend that you " dongsheng@627: "upgrade." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch08-branch.xml:5 dongsheng@627: msgid "Managing releases and branchy development" dongsheng@627: msgstr "发布管理与分支开发" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch08-branch.xml:7 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides several mechanisms for you to manage a project that is " dongsheng@627: "making progress on multiple fronts at once. To understand these mechanisms, " dongsheng@627: "let's first take a brief look at a fairly normal software project structure." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch08-branch.xml:12 dongsheng@627: msgid "" dongsheng@627: "Many software projects issue periodic <quote>major</quote> releases that " dongsheng@627: "contain substantial new features. In parallel, they may issue <quote>minor</" dongsheng@627: "quote> releases. These are usually identical to the major releases off which " dongsheng@627: "they're based, but with a few bugs fixed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch08-branch.xml:18 dongsheng@627: msgid "" dongsheng@627: "In this chapter, we'll start by talking about how to keep records of project " dongsheng@627: "milestones such as releases. We'll then continue on to talk about the flow " dongsheng@627: "of work between different phases of a project, and how Mercurial can help you " dongsheng@627: "to isolate and manage this work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:25 dongsheng@627: msgid "Giving a persistent name to a revision" dongsheng@635: msgstr "给版本指定一个永久的名称" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:27 dongsheng@627: msgid "" dongsheng@627: "Once you decide that you'd like to call a particular revision a " dongsheng@627: "<quote>release</quote>, it's a good idea to record the identity of that " dongsheng@627: "revision. This will let you reproduce that release at a later date, for " dongsheng@627: "whatever purpose you might need at the time (reproducing a bug, porting to a " dongsheng@627: "new platform, etc). &interaction.tag.init;" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:34 dongsheng@627: msgid "" dongsheng@627: "Mercurial lets you give a permanent name to any revision using the <command " dongsheng@627: "role=\"hg-cmd\">hg tag</command> command. Not surprisingly, these names are " dongsheng@627: "called <quote>tags</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:40 dongsheng@627: msgid "" dongsheng@627: "A tag is nothing more than a <quote>symbolic name</quote> for a revision. " dongsheng@627: "Tags exist purely for your convenience, so that you have a handy permanent " dongsheng@627: "way to refer to a revision; Mercurial doesn't interpret the tag names you use " dongsheng@627: "in any way. Neither does Mercurial place any restrictions on the name of a " dongsheng@627: "tag, beyond a few that are necessary to ensure that a tag can be parsed " dongsheng@627: "unambiguously. A tag name cannot contain any of the following characters:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:49 dongsheng@627: msgid "Colon (ASCII 58, <quote><literal>:</literal></quote>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:52 dongsheng@627: msgid "Carriage return (ASCII 13, <quote><literal>\\r</literal></quote>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:55 dongsheng@627: msgid "Newline (ASCII 10, <quote><literal>\\n</literal></quote>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:59 dongsheng@627: msgid "" dongsheng@627: "You can use the <command role=\"hg-cmd\">hg tags</command> command to display " dongsheng@627: "the tags present in your repository. In the output, each tagged revision is " dongsheng@627: "identified first by its name, then by revision number, and finally by the " dongsheng@627: "unique hash of the revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:67 dongsheng@627: msgid "" dongsheng@627: "Notice that <literal>tip</literal> is listed in the output of <command role=" dongsheng@627: "\"hg-cmd\">hg tags</command>. The <literal>tip</literal> tag is a special " dongsheng@627: "<quote>floating</quote> tag, which always identifies the newest revision in " dongsheng@627: "the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:73 dongsheng@627: msgid "" dongsheng@627: "In the output of the <command role=\"hg-cmd\">hg tags</command> command, tags " dongsheng@627: "are listed in reverse order, by revision number. This usually means that " dongsheng@627: "recent tags are listed before older tags. It also means that <literal>tip</" dongsheng@627: "literal> is always going to be the first tag listed in the output of <command " dongsheng@627: "role=\"hg-cmd\">hg tags</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:80 dongsheng@627: msgid "" dongsheng@627: "When you run <command role=\"hg-cmd\">hg log</command>, if it displays a " dongsheng@627: "revision that has tags associated with it, it will print those tags." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:86 dongsheng@627: msgid "" dongsheng@627: "Any time you need to provide a revision ID to a Mercurial command, the " dongsheng@627: "command will accept a tag name in its place. Internally, Mercurial will " dongsheng@627: "translate your tag name into the corresponding revision ID, then use that." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:93 dongsheng@627: msgid "" dongsheng@627: "There's no limit on the number of tags you can have in a repository, or on " dongsheng@627: "the number of tags that a single revision can have. As a practical matter, " dongsheng@627: "it's not a great idea to have <quote>too many</quote> (a number which will " dongsheng@627: "vary from project to project), simply because tags are supposed to help you " dongsheng@627: "to find revisions. If you have lots of tags, the ease of using them to " dongsheng@627: "identify revisions diminishes rapidly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:101 dongsheng@627: msgid "" dongsheng@627: "For example, if your project has milestones as frequent as every few days, " dongsheng@627: "it's perfectly reasonable to tag each one of those. But if you have a " dongsheng@627: "continuous build system that makes sure every revision can be built cleanly, " dongsheng@627: "you'd be introducing a lot of noise if you were to tag every clean build. " dongsheng@627: "Instead, you could tag failed builds (on the assumption that they're rare!), " dongsheng@627: "or simply not use tags to track buildability." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:109 dongsheng@627: msgid "" dongsheng@627: "If you want to remove a tag that you no longer want, use <command role=\"hg-" dongsheng@627: "cmd\">hg tag --remove</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:114 dongsheng@627: msgid "" dongsheng@627: "You can also modify a tag at any time, so that it identifies a different " dongsheng@627: "revision, by simply issuing a new <command role=\"hg-cmd\">hg tag</command> " dongsheng@627: "command. You'll have to use the <option role=\"hg-opt-tag\">-f</option> " dongsheng@627: "option to tell Mercurial that you <emphasis>really</emphasis> want to update " dongsheng@627: "the tag." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:123 dongsheng@627: msgid "" dongsheng@627: "There will still be a permanent record of the previous identity of the tag, " dongsheng@627: "but Mercurial will no longer use it. There's thus no penalty to tagging the " dongsheng@627: "wrong revision; all you have to do is turn around and tag the correct " dongsheng@627: "revision once you discover your error." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:129 dongsheng@627: msgid "" dongsheng@627: "Mercurial stores tags in a normal revision-controlled file in your " dongsheng@627: "repository. If you've created any tags, you'll find them in a file named " dongsheng@627: "<filename role=\"special\">.hgtags</filename>. When you run the <command " dongsheng@627: "role=\"hg-cmd\">hg tag</command> command, Mercurial modifies this file, then " dongsheng@627: "automatically commits the change to it. This means that every time you run " dongsheng@627: "<command role=\"hg-cmd\">hg tag</command>, you'll see a corresponding " dongsheng@627: "changeset in the output of <command role=\"hg-cmd\">hg log</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch08-branch.xml:142 dongsheng@627: msgid "Handling tag conflicts during a merge" dongsheng@635: msgstr "在合并期间处理标签冲突" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:144 dongsheng@627: msgid "" dongsheng@627: "You won't often need to care about the <filename role=\"special\">.hgtags</" dongsheng@627: "filename> file, but it sometimes makes its presence known during a merge. " dongsheng@627: "The format of the file is simple: it consists of a series of lines. Each " dongsheng@627: "line starts with a changeset hash, followed by a space, followed by the name " dongsheng@627: "of a tag." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:151 dongsheng@627: msgid "" dongsheng@627: "If you're resolving a conflict in the <filename role=\"special\">.hgtags</" dongsheng@627: "filename> file during a merge, there's one twist to modifying the <filename " dongsheng@627: "role=\"special\">.hgtags</filename> file: when Mercurial is parsing the tags " dongsheng@627: "in a repository, it <emphasis>never</emphasis> reads the working copy of the " dongsheng@627: "<filename role=\"special\">.hgtags</filename> file. Instead, it reads the " dongsheng@627: "<emphasis>most recently committed</emphasis> revision of the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:161 dongsheng@627: msgid "" dongsheng@627: "An unfortunate consequence of this design is that you can't actually verify " dongsheng@627: "that your merged <filename role=\"special\">.hgtags</filename> file is " dongsheng@627: "correct until <emphasis>after</emphasis> you've committed a change. So if " dongsheng@627: "you find yourself resolving a conflict on <filename role=\"special\">.hgtags</" dongsheng@627: "filename> during a merge, be sure to run <command role=\"hg-cmd\">hg tags</" dongsheng@627: "command> after you commit. If it finds an error in the <filename role=" dongsheng@627: "\"special\">.hgtags</filename> file, it will report the location of the " dongsheng@627: "error, which you can then fix and commit. You should then run <command role=" dongsheng@627: "\"hg-cmd\">hg tags</command> again, just to be sure that your fix is correct." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch08-branch.xml:176 dongsheng@627: msgid "Tags and cloning" dongsheng@635: msgstr "标签与克隆" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:178 dongsheng@627: msgid "" dongsheng@627: "You may have noticed that the <command role=\"hg-cmd\">hg clone</command> " dongsheng@627: "command has a <option role=\"hg-opt-clone\">-r</option> option that lets you " dongsheng@627: "clone an exact copy of the repository as of a particular changeset. The new " dongsheng@627: "clone will not contain any project history that comes after the revision you " dongsheng@627: "specified. This has an interaction with tags that can surprise the unwary." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:186 dongsheng@627: msgid "" dongsheng@627: "Recall that a tag is stored as a revision to the <filename role=\"special\">." dongsheng@627: "hgtags</filename> file, so that when you create a tag, the changeset in which " dongsheng@627: "it's recorded necessarily refers to an older changeset. When you run " dongsheng@627: "<command role=\"hg-cmd\">hg clone -r foo</command> to clone a repository as " dongsheng@627: "of tag <literal>foo</literal>, the new clone <emphasis>will not contain the " dongsheng@627: "history that created the tag</emphasis> that you used to clone the " dongsheng@627: "repository. The result is that you'll get exactly the right subset of the " dongsheng@627: "project's history in the new repository, but <emphasis>not</emphasis> the tag " dongsheng@627: "you might have expected." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch08-branch.xml:201 dongsheng@627: msgid "When permanent tags are too much" dongsheng@635: msgstr "当永久标签太多的时候" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:203 dongsheng@627: msgid "" dongsheng@627: "Since Mercurial's tags are revision controlled and carried around with a " dongsheng@627: "project's history, everyone you work with will see the tags you create. But " dongsheng@627: "giving names to revisions has uses beyond simply noting that revision " dongsheng@627: "<literal>4237e45506ee</literal> is really <literal>v2.0.2</literal>. If " dongsheng@627: "you're trying to track down a subtle bug, you might want a tag to remind you " dongsheng@627: "of something like <quote>Anne saw the symptoms with this revision</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch08-branch.xml:213 dongsheng@627: msgid "" dongsheng@627: "For cases like this, what you might want to use are <emphasis>local</" dongsheng@627: "emphasis> tags. You can create a local tag with the <option role=\"hg-opt-tag" dongsheng@627: "\">-l</option> option to the <command role=\"hg-cmd\">hg tag</command> " dongsheng@627: "command. This will store the tag in a file called <filename role=\"special" dongsheng@627: "\">.hg/localtags</filename>. Unlike <filename role=\"special\">.hgtags</" dongsheng@627: "filename>, <filename role=\"special\">.hg/localtags</filename> is not " dongsheng@627: "revision controlled. Any tags you create using <option role=\"hg-opt-tag\">-" dongsheng@627: "l</option> remain strictly local to the repository you're currently working " dongsheng@627: "in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:228 dongsheng@627: msgid "The flow of changes&emdash;big picture vs. little" dongsheng@635: msgstr "修改流程&emdash;宏观与微观" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:230 dongsheng@627: msgid "" dongsheng@627: "To return to the outline I sketched at the beginning of a chapter, let's " dongsheng@627: "think about a project that has multiple concurrent pieces of work under " dongsheng@627: "development at once." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:234 dongsheng@627: msgid "" dongsheng@627: "There might be a push for a new <quote>main</quote> release; a new minor " dongsheng@627: "bugfix release to the last main release; and an unexpected <quote>hot fix</" dongsheng@627: "quote> to an old release that is now in maintenance mode." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:239 dongsheng@627: msgid "" dongsheng@627: "The usual way people refer to these different concurrent directions of " dongsheng@627: "development is as <quote>branches</quote>. However, we've already seen " dongsheng@627: "numerous times that Mercurial treats <emphasis>all of history</emphasis> as a " dongsheng@627: "series of branches and merges. Really, what we have here is two ideas that " dongsheng@627: "are peripherally related, but which happen to share a name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:246 dongsheng@627: msgid "" dongsheng@627: "<quote>Big picture</quote> branches represent the sweep of a project's " dongsheng@627: "evolution; people give them names, and talk about them in conversation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch08-branch.xml:250 dongsheng@627: msgid "" dongsheng@627: "<quote>Little picture</quote> branches are artefacts of the day-to-day " dongsheng@627: "activity of developing and merging changes. They expose the narrative of how " dongsheng@627: "the code was developed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:258 dongsheng@627: msgid "Managing big-picture branches in repositories" dongsheng@635: msgstr "在版本库中管理分支" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:260 dongsheng@627: msgid "" dongsheng@627: "The easiest way to isolate a <quote>big picture</quote> branch in Mercurial " dongsheng@627: "is in a dedicated repository. If you have an existing shared " dongsheng@627: "repository&emdash;let's call it <literal>myproject</literal>&emdash;that " dongsheng@627: "reaches a <quote>1.0</quote> milestone, you can start to prepare for future " dongsheng@627: "maintenance releases on top of version 1.0 by tagging the revision from which " dongsheng@627: "you prepared the 1.0 release." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:270 dongsheng@627: msgid "" dongsheng@627: "You can then clone a new shared <literal>myproject-1.0.1</literal> repository " dongsheng@627: "as of that tag." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:276 dongsheng@627: msgid "" dongsheng@627: "Afterwards, if someone needs to work on a bug fix that ought to go into an " dongsheng@627: "upcoming 1.0.1 minor release, they clone the <literal>myproject-1.0.1</" dongsheng@627: "literal> repository, make their changes, and push them back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:283 dongsheng@627: msgid "" dongsheng@627: "Meanwhile, development for the next major release can continue, isolated and " dongsheng@627: "unabated, in the <literal>myproject</literal> repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:291 dongsheng@627: msgid "Don't repeat yourself: merging across branches" dongsheng@635: msgstr "不要重复劳动：在分支间合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:293 dongsheng@627: msgid "" dongsheng@627: "In many cases, if you have a bug to fix on a maintenance branch, the chances " dongsheng@627: "are good that the bug exists on your project's main branch (and possibly " dongsheng@627: "other maintenance branches, too). It's a rare developer who wants to fix the " dongsheng@627: "same bug multiple times, so let's look at a few ways that Mercurial can help " dongsheng@627: "you to manage these bugfixes without duplicating your work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:301 dongsheng@627: msgid "" dongsheng@627: "In the simplest instance, all you need to do is pull changes from your " dongsheng@627: "maintenance branch into your local clone of the target branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:307 dongsheng@627: msgid "" dongsheng@627: "You'll then need to merge the heads of the two branches, and push back to the " dongsheng@627: "main branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:314 dongsheng@627: msgid "Naming branches within one repository" dongsheng@635: msgstr "版本库中的命名分支" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:316 dongsheng@627: msgid "" dongsheng@627: "In most instances, isolating branches in repositories is the right approach. " dongsheng@627: "Its simplicity makes it easy to understand; and so it's hard to make " dongsheng@627: "mistakes. There's a one-to-one relationship between branches you're working " dongsheng@627: "in and directories on your system. This lets you use normal (non-Mercurial-" dongsheng@627: "aware) tools to work on files within a branch/repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:323 dongsheng@627: msgid "" dongsheng@627: "If you're more in the <quote>power user</quote> category (<emphasis>and</" dongsheng@627: "emphasis> your collaborators are too), there is an alternative way of " dongsheng@627: "handling branches that you can consider. I've already mentioned the human-" dongsheng@627: "level distinction between <quote>small picture</quote> and <quote>big " dongsheng@627: "picture</quote> branches. While Mercurial works with multiple <quote>small " dongsheng@627: "picture</quote> branches in a repository all the time (for example after you " dongsheng@627: "pull changes in, but before you merge them), it can <emphasis>also</emphasis> " dongsheng@627: "work with multiple <quote>big picture</quote> branches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:334 dongsheng@627: msgid "" dongsheng@627: "The key to working this way is that Mercurial lets you assign a persistent " dongsheng@627: "<emphasis>name</emphasis> to a branch. There always exists a branch named " dongsheng@627: "<literal>default</literal>. Even before you start naming branches yourself, " dongsheng@627: "you can find traces of the <literal>default</literal> branch if you look for " dongsheng@627: "them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:341 dongsheng@627: msgid "" dongsheng@627: "As an example, when you run the <command role=\"hg-cmd\">hg commit</command> " dongsheng@627: "command, and it pops up your editor so that you can enter a commit message, " dongsheng@627: "look for a line that contains the text <quote><literal>HG: branch default</" dongsheng@627: "literal></quote> at the bottom. This is telling you that your commit will " dongsheng@627: "occur on the branch named <literal>default</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:348 dongsheng@627: msgid "" dongsheng@627: "To start working with named branches, use the <command role=\"hg-cmd\">hg " dongsheng@627: "branches</command> command. This command lists the named branches already " dongsheng@627: "present in your repository, telling you which changeset is the tip of each." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:355 dongsheng@627: msgid "" dongsheng@627: "Since you haven't created any named branches yet, the only one that exists is " dongsheng@627: "<literal>default</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:358 dongsheng@627: msgid "" dongsheng@627: "To find out what the <quote>current</quote> branch is, run the <command role=" dongsheng@627: "\"hg-cmd\">hg branch</command> command, giving it no arguments. This tells " dongsheng@627: "you what branch the parent of the current changeset is on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:365 dongsheng@627: msgid "" dongsheng@627: "To create a new branch, run the <command role=\"hg-cmd\">hg branch</command> " dongsheng@627: "command again. This time, give it one argument: the name of the branch you " dongsheng@627: "want to create." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:371 dongsheng@627: msgid "" dongsheng@627: "After you've created a branch, you might wonder what effect the <command role=" dongsheng@627: "\"hg-cmd\">hg branch</command> command has had. What do the <command role=" dongsheng@627: "\"hg-cmd\">hg status</command> and <command role=\"hg-cmd\">hg tip</command> " dongsheng@627: "commands report?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:378 dongsheng@627: msgid "" dongsheng@627: "Nothing has changed in the working directory, and there's been no new history " dongsheng@627: "created. As this suggests, running the <command role=\"hg-cmd\">hg branch</" dongsheng@627: "command> command has no permanent effect; it only tells Mercurial what branch " dongsheng@627: "name to use the <emphasis>next</emphasis> time you commit a changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:385 dongsheng@627: msgid "" dongsheng@627: "When you commit a change, Mercurial records the name of the branch on which " dongsheng@627: "you committed. Once you've switched from the <literal>default</literal> " dongsheng@627: "branch to another and committed, you'll see the name of the new branch show " dongsheng@627: "up in the output of <command role=\"hg-cmd\">hg log</command>, <command role=" dongsheng@627: "\"hg-cmd\">hg tip</command>, and other commands that display the same kind of " dongsheng@627: "output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:395 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg log</command>-like commands will print the " dongsheng@627: "branch name of every changeset that's not on the <literal>default</literal> " dongsheng@627: "branch. As a result, if you never use named branches, you'll never see this " dongsheng@627: "information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:400 dongsheng@627: msgid "" dongsheng@627: "Once you've named a branch and committed a change with that name, every " dongsheng@627: "subsequent commit that descends from that change will inherit the same branch " dongsheng@627: "name. You can change the name of a branch at any time, using the <command " dongsheng@627: "role=\"hg-cmd\">hg branch</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:408 dongsheng@627: msgid "" dongsheng@627: "In practice, this is something you won't do very often, as branch names tend " dongsheng@627: "to have fairly long lifetimes. (This isn't a rule, just an observation.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:414 dongsheng@627: msgid "Dealing with multiple named branches in a repository" dongsheng@635: msgstr "在版本库中处理多个命名分支" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:417 dongsheng@627: msgid "" dongsheng@627: "If you have more than one named branch in a repository, Mercurial will " dongsheng@627: "remember the branch that your working directory on when you start a command " dongsheng@627: "like <command role=\"hg-cmd\">hg update</command> or <command role=\"hg-cmd" dongsheng@627: "\">hg pull -u</command>. It will update the working directory to the tip of " dongsheng@627: "this branch, no matter what the <quote>repo-wide</quote> tip is. To update " dongsheng@627: "to a revision that's on a different named branch, you may need to use the " dongsheng@627: "<option role=\"hg-opt-update\">-C</option> option to <command role=\"hg-cmd" dongsheng@627: "\">hg update</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:427 dongsheng@627: msgid "" dongsheng@627: "This behaviour is a little subtle, so let's see it in action. First, let's " dongsheng@627: "remind ourselves what branch we're currently on, and what branches are in our " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:433 dongsheng@627: msgid "" dongsheng@627: "We're on the <literal>bar</literal> branch, but there also exists an older " dongsheng@627: "<command role=\"hg-cmd\">hg foo</command> branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:437 dongsheng@627: msgid "" dongsheng@627: "We can <command role=\"hg-cmd\">hg update</command> back and forth between " dongsheng@627: "the tips of the <literal>foo</literal> and <literal>bar</literal> branches " dongsheng@627: "without needing to use the <option role=\"hg-opt-update\">-C</option> option, " dongsheng@627: "because this only involves going backwards and forwards linearly through our " dongsheng@627: "change history." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:446 dongsheng@627: msgid "" dongsheng@627: "If we go back to the <literal>foo</literal> branch and then run <command role=" dongsheng@627: "\"hg-cmd\">hg update</command>, it will keep us on <literal>foo</literal>, " dongsheng@627: "not move us to the tip of <literal>bar</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:453 dongsheng@627: msgid "" dongsheng@627: "Committing a new change on the <literal>foo</literal> branch introduces a new " dongsheng@627: "head." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:460 dongsheng@627: msgid "Branch names and merging" dongsheng@635: msgstr "分支名称与合并" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:462 dongsheng@627: msgid "" dongsheng@627: "As you've probably noticed, merges in Mercurial are not symmetrical. Let's " dongsheng@627: "say our repository has two heads, 17 and 23. If I <command role=\"hg-cmd" dongsheng@627: "\">hg update</command> to 17 and then <command role=\"hg-cmd\">hg merge</" dongsheng@627: "command> with 23, Mercurial records 17 as the first parent of the merge, and " dongsheng@627: "23 as the second. Whereas if I <command role=\"hg-cmd\">hg update</command> " dongsheng@627: "to 23 and then <command role=\"hg-cmd\">hg merge</command> with 17, it " dongsheng@627: "records 23 as the first parent, and 17 as the second." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:472 dongsheng@627: msgid "" dongsheng@627: "This affects Mercurial's choice of branch name when you merge. After a " dongsheng@627: "merge, Mercurial will retain the branch name of the first parent when you " dongsheng@627: "commit the result of the merge. If your first parent's branch name is " dongsheng@627: "<literal>foo</literal>, and you merge with <literal>bar</literal>, the branch " dongsheng@627: "name will still be <literal>foo</literal> after you merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:479 dongsheng@627: msgid "" dongsheng@627: "It's not unusual for a repository to contain multiple heads, each with the " dongsheng@627: "same branch name. Let's say I'm working on the <literal>foo</literal> " dongsheng@627: "branch, and so are you. We commit different changes; I pull your changes; I " dongsheng@627: "now have two heads, each claiming to be on the <literal>foo</literal> " dongsheng@627: "branch. The result of a merge will be a single head on the <literal>foo</" dongsheng@627: "literal> branch, as you might hope." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:487 dongsheng@627: msgid "" dongsheng@627: "But if I'm working on the <literal>bar</literal> branch, and I merge work " dongsheng@627: "from the <literal>foo</literal> branch, the result will remain on the " dongsheng@627: "<literal>bar</literal> branch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:493 dongsheng@627: msgid "" dongsheng@627: "To give a more concrete example, if I'm working on the <literal>bleeding-" dongsheng@627: "edge</literal> branch, and I want to bring in the latest fixes from the " dongsheng@627: "<literal>stable</literal> branch, Mercurial will choose the <quote>right</" dongsheng@627: "quote> (<literal>bleeding-edge</literal>) branch name when I pull and merge " dongsheng@627: "from <literal>stable</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch08-branch.xml:502 dongsheng@627: msgid "Branch naming is generally useful" dongsheng@635: msgstr "分支名称通常都很有用" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:504 dongsheng@627: msgid "" dongsheng@627: "You shouldn't think of named branches as applicable only to situations where " dongsheng@627: "you have multiple long-lived branches cohabiting in a single repository. " dongsheng@627: "They're very useful even in the one-branch-per-repository case." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:509 dongsheng@627: msgid "" dongsheng@627: "In the simplest case, giving a name to each branch gives you a permanent " dongsheng@627: "record of which branch a changeset originated on. This gives you more " dongsheng@627: "context when you're trying to follow the history of a long-lived branchy " dongsheng@627: "project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch08-branch.xml:514 dongsheng@627: msgid "" dongsheng@627: "If you're working with shared repositories, you can set up a <literal role=" dongsheng@627: "\"hook\">pretxnchangegroup</literal> hook on each that will block incoming " dongsheng@627: "changes that have the <quote>wrong</quote> branch name. This provides a " dongsheng@627: "simple, but effective, defence against people accidentally pushing changes " dongsheng@627: "from a <quote>bleeding edge</quote> branch to a <quote>stable</quote> " dongsheng@627: "branch. Such a hook might look like this inside the shared repo's <filename " dongsheng@627: "role=\"special\"> /.hgrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch09-undo.xml:5 dongsheng@627: msgid "Finding and fixing mistakes" dongsheng@627: msgstr "查找和修改错误" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch09-undo.xml:7 dongsheng@627: msgid "" dongsheng@627: "To err might be human, but to really handle the consequences well takes a top-" dongsheng@627: "notch revision control system. In this chapter, we'll discuss some of the " dongsheng@627: "techniques you can use when you find that a problem has crept into your " dongsheng@627: "project. Mercurial has some highly capable features that will help you to " dongsheng@627: "isolate the sources of problems, and to handle them appropriately." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:15 dongsheng@627: msgid "Erasing local history" dongsheng@635: msgstr "销毁本地历史" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:18 dongsheng@627: msgid "The accidental commit" dongsheng@635: msgstr "意外的提交" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:20 dongsheng@627: msgid "" dongsheng@627: "I have the occasional but persistent problem of typing rather more quickly " dongsheng@627: "than I can think, which sometimes results in me committing a changeset that " dongsheng@627: "is either incomplete or plain wrong. In my case, the usual kind of " dongsheng@627: "incomplete changeset is one in which I've created a new source file, but " dongsheng@627: "forgotten to <command role=\"hg-cmd\">hg add</command> it. A <quote>plain " dongsheng@627: "wrong</quote> changeset is not as common, but no less annoying." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:31 dongsheng@627: msgid "Rolling back a transaction" dongsheng@635: msgstr "回滚一个事务" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:33 dongsheng@627: msgid "" dongsheng@627: "In section <xref linkend=\"sec.concepts.txn\"/>, I mentioned that Mercurial " dongsheng@627: "treats each modification of a repository as a <emphasis>transaction</" dongsheng@627: "emphasis>. Every time you commit a changeset or pull changes from another " dongsheng@627: "repository, Mercurial remembers what you did. You can undo, or " dongsheng@627: "<emphasis>roll back</emphasis>, exactly one of these actions using the " dongsheng@627: "<command role=\"hg-cmd\">hg rollback</command> command. (See section <xref " dongsheng@627: "linkend=\"sec.undo.rollback-after-push\"/> for an important caveat about the " dongsheng@627: "use of this command.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:43 dongsheng@627: msgid "" dongsheng@627: "Here's a mistake that I often find myself making: committing a change in " dongsheng@627: "which I've created a new file, but forgotten to <command role=\"hg-cmd\">hg " dongsheng@627: "add</command> it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:50 dongsheng@627: msgid "" dongsheng@627: "Looking at the output of <command role=\"hg-cmd\">hg status</command> after " dongsheng@627: "the commit immediately confirms the error." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:56 dongsheng@627: msgid "" dongsheng@627: "The commit captured the changes to the file <filename>a</filename>, but not " dongsheng@627: "the new file <filename>b</filename>. If I were to push this changeset to a " dongsheng@627: "repository that I shared with a colleague, the chances are high that " dongsheng@627: "something in <filename>a</filename> would refer to <filename>b</filename>, " dongsheng@627: "which would not be present in their repository when they pulled my changes. " dongsheng@627: "I would thus become the object of some indignation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:65 dongsheng@627: msgid "" dongsheng@627: "However, luck is with me&emdash;I've caught my error before I pushed the " dongsheng@627: "changeset. I use the <command role=\"hg-cmd\">hg rollback</command> command, " dongsheng@627: "and Mercurial makes that last changeset vanish." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:72 dongsheng@627: msgid "" dongsheng@627: "Notice that the changeset is no longer present in the repository's history, " dongsheng@627: "and the working directory once again thinks that the file <filename>a</" dongsheng@627: "filename> is modified. The commit and rollback have left the working " dongsheng@627: "directory exactly as it was prior to the commit; the changeset has been " dongsheng@627: "completely erased. I can now safely <command role=\"hg-cmd\">hg add</" dongsheng@627: "command> the file <filename>b</filename>, and rerun my commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:85 dongsheng@627: msgid "The erroneous pull" dongsheng@635: msgstr "错误的抓取" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:87 dongsheng@627: msgid "" dongsheng@627: "It's common practice with Mercurial to maintain separate development branches " dongsheng@627: "of a project in different repositories. Your development team might have one " dongsheng@627: "shared repository for your project's <quote>0.9</quote> release, and another, " dongsheng@627: "containing different changes, for the <quote>1.0</quote> release." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:94 dongsheng@627: msgid "" dongsheng@627: "Given this, you can imagine that the consequences could be messy if you had a " dongsheng@627: "local <quote>0.9</quote> repository, and accidentally pulled changes from the " dongsheng@627: "shared <quote>1.0</quote> repository into it. At worst, you could be paying " dongsheng@627: "insufficient attention, and push those changes into the shared <quote>0.9</" dongsheng@627: "quote> tree, confusing your entire team (but don't worry, we'll return to " dongsheng@627: "this horror scenario later). However, it's more likely that you'll notice " dongsheng@627: "immediately, because Mercurial will display the URL it's pulling from, or you " dongsheng@627: "will see it pull a suspiciously large number of changes into the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:106 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg rollback</command> command will work nicely " dongsheng@627: "to expunge all of the changesets that you just pulled. Mercurial groups all " dongsheng@627: "changes from one <command role=\"hg-cmd\">hg pull</command> into a single " dongsheng@627: "transaction, so one <command role=\"hg-cmd\">hg rollback</command> is all you " dongsheng@627: "need to undo this mistake." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:115 dongsheng@627: msgid "Rolling back is useless once you've pushed" dongsheng@635: msgstr "当完成推送后，回滚是无效的" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:117 dongsheng@627: msgid "" dongsheng@627: "The value of the <command role=\"hg-cmd\">hg rollback</command> command drops " dongsheng@627: "to zero once you've pushed your changes to another repository. Rolling back " dongsheng@627: "a change makes it disappear entirely, but <emphasis>only</emphasis> in the " dongsheng@627: "repository in which you perform the <command role=\"hg-cmd\">hg rollback</" dongsheng@627: "command>. Because a rollback eliminates history, there's no way for the " dongsheng@627: "disappearance of a change to propagate between repositories." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:126 dongsheng@627: msgid "" dongsheng@627: "If you've pushed a change to another repository&emdash;particularly if it's a " dongsheng@627: "shared repository&emdash;it has essentially <quote>escaped into the wild,</" dongsheng@627: "quote> and you'll have to recover from your mistake in a different way. What " dongsheng@627: "will happen if you push a changeset somewhere, then roll it back, then pull " dongsheng@627: "from the repository you pushed to, is that the changeset will reappear in " dongsheng@627: "your repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:135 dongsheng@627: msgid "" dongsheng@627: "(If you absolutely know for sure that the change you want to roll back is the " dongsheng@627: "most recent change in the repository that you pushed to, <emphasis>and</" dongsheng@627: "emphasis> you know that nobody else could have pulled it from that " dongsheng@627: "repository, you can roll back the changeset there, too, but you really should " dongsheng@627: "really not rely on this working reliably. If you do this, sooner or later a " dongsheng@627: "change really will make it into a repository that you don't directly control " dongsheng@627: "(or have forgotten about), and come back to bite you.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:147 dongsheng@627: msgid "You can only roll back once" dongsheng@635: msgstr "你只能回滚一次" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:149 dongsheng@627: msgid "" dongsheng@627: "Mercurial stores exactly one transaction in its transaction log; that " dongsheng@627: "transaction is the most recent one that occurred in the repository. This " dongsheng@627: "means that you can only roll back one transaction. If you expect to be able " dongsheng@627: "to roll back one transaction, then its predecessor, this is not the behaviour " dongsheng@627: "you will get." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:158 dongsheng@627: msgid "" dongsheng@627: "Once you've rolled back one transaction in a repository, you can't roll back " dongsheng@627: "again in that repository until you perform another commit or pull." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:165 dongsheng@627: msgid "Reverting the mistaken change" dongsheng@635: msgstr "撤销错误的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:167 dongsheng@627: msgid "" dongsheng@627: "If you make a modification to a file, and decide that you really didn't want " dongsheng@627: "to change the file at all, and you haven't yet committed your changes, the " dongsheng@627: "<command role=\"hg-cmd\">hg revert</command> command is the one you'll need. " dongsheng@627: "It looks at the changeset that's the parent of the working directory, and " dongsheng@627: "restores the contents of the file to their state as of that changeset. " dongsheng@627: "(That's a long-winded way of saying that, in the normal case, it undoes your " dongsheng@627: "modifications.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:176 dongsheng@627: msgid "" dongsheng@627: "Let's illustrate how the <command role=\"hg-cmd\">hg revert</command> command " dongsheng@627: "works with yet another small example. We'll begin by modifying a file that " dongsheng@627: "Mercurial is already tracking." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:183 dongsheng@627: msgid "" dongsheng@627: "If we don't want that change, we can simply <command role=\"hg-cmd\">hg " dongsheng@627: "revert</command> the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:189 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg revert</command> command provides us with an " dongsheng@627: "extra degree of safety by saving our modified file with a <filename>.orig</" dongsheng@627: "filename> extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:196 dongsheng@627: msgid "" dongsheng@627: "Here is a summary of the cases that the <command role=\"hg-cmd\">hg revert</" dongsheng@627: "command> command can deal with. We will describe each of these in more " dongsheng@627: "detail in the section that follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:201 dongsheng@627: msgid "If you modify a file, it will restore the file to its unmodified state." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:204 dongsheng@627: msgid "" dongsheng@627: "If you <command role=\"hg-cmd\">hg add</command> a file, it will undo the " dongsheng@627: "<quote>added</quote> state of the file, but leave the file itself untouched." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:208 dongsheng@627: msgid "" dongsheng@627: "If you delete a file without telling Mercurial, it will restore the file to " dongsheng@627: "its unmodified contents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:211 dongsheng@627: msgid "" dongsheng@627: "If you use the <command role=\"hg-cmd\">hg remove</command> command to remove " dongsheng@627: "a file, it will undo the <quote>removed</quote> state of the file, and " dongsheng@627: "restore the file to its unmodified contents." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:218 dongsheng@627: msgid "File management errors" dongsheng@635: msgstr "文件管理错误" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:220 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg revert</command> command is useful for more " dongsheng@627: "than just modified files. It lets you reverse the results of all of " dongsheng@627: "Mercurial's file management commands&emdash;<command role=\"hg-cmd\">hg add</" dongsheng@627: "command>, <command role=\"hg-cmd\">hg remove</command>, and so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:226 dongsheng@627: msgid "" dongsheng@627: "If you <command role=\"hg-cmd\">hg add</command> a file, then decide that in " dongsheng@627: "fact you don't want Mercurial to track it, use <command role=\"hg-cmd\">hg " dongsheng@627: "revert</command> to undo the add. Don't worry; Mercurial will not modify the " dongsheng@627: "file in any way. It will just <quote>unmark</quote> the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:234 dongsheng@627: msgid "" dongsheng@627: "Similarly, if you ask Mercurial to <command role=\"hg-cmd\">hg remove</" dongsheng@627: "command> a file, you can use <command role=\"hg-cmd\">hg revert</command> to " dongsheng@627: "restore it to the contents it had as of the parent of the working directory. " dongsheng@627: "&interaction.daily.revert.remove; This works just as well for a file that you " dongsheng@627: "deleted by hand, without telling Mercurial (recall that in Mercurial " dongsheng@627: "terminology, this kind of file is called <quote>missing</quote>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:245 dongsheng@627: msgid "" dongsheng@627: "If you revert a <command role=\"hg-cmd\">hg copy</command>, the copied-to " dongsheng@627: "file remains in your working directory afterwards, untracked. Since a copy " dongsheng@627: "doesn't affect the copied-from file in any way, Mercurial doesn't do anything " dongsheng@627: "with the copied-from file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch09-undo.xml:254 dongsheng@627: msgid "A slightly special case: reverting a rename" dongsheng@635: msgstr "一个稍微特别的案例：撤销改名" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:256 dongsheng@627: msgid "" dongsheng@627: "If you <command role=\"hg-cmd\">hg rename</command> a file, there is one " dongsheng@627: "small detail that you should remember. When you <command role=\"hg-cmd\">hg " dongsheng@627: "revert</command> a rename, it's not enough to provide the name of the renamed-" dongsheng@627: "to file, as you can see here." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:264 dongsheng@627: msgid "" dongsheng@627: "As you can see from the output of <command role=\"hg-cmd\">hg status</" dongsheng@627: "command>, the renamed-to file is no longer identified as added, but the " dongsheng@627: "renamed-<emphasis>from</emphasis> file is still removed! This is counter-" dongsheng@627: "intuitive (at least to me), but at least it's easy to deal with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:273 dongsheng@627: msgid "" dongsheng@627: "So remember, to revert a <command role=\"hg-cmd\">hg rename</command>, you " dongsheng@627: "must provide <emphasis>both</emphasis> the source and destination names." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:278 dongsheng@627: msgid "% TODO: the output doesn't look like it will be removed!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:281 dongsheng@627: msgid "" dongsheng@627: "(By the way, if you rename a file, then modify the renamed-to file, then " dongsheng@627: "revert both components of the rename, when Mercurial restores the file that " dongsheng@627: "was removed as part of the rename, it will be unmodified. If you need the " dongsheng@627: "modifications in the renamed-to file to show up in the renamed-from file, " dongsheng@627: "don't forget to copy them over.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:288 dongsheng@627: msgid "" dongsheng@627: "These fiddly aspects of reverting a rename arguably constitute a small bug in " dongsheng@627: "Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:295 dongsheng@627: msgid "Dealing with committed changes" dongsheng@635: msgstr "处理已经提交的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:297 dongsheng@627: msgid "" dongsheng@627: "Consider a case where you have committed a change $a$, and another change $b$ " dongsheng@627: "on top of it; you then realise that change $a$ was incorrect. Mercurial lets " dongsheng@627: "you <quote>back out</quote> an entire changeset automatically, and building " dongsheng@627: "blocks that let you reverse part of a changeset by hand." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:303 dongsheng@627: msgid "" dongsheng@627: "Before you read this section, here's something to keep in mind: the <command " dongsheng@627: "role=\"hg-cmd\">hg backout</command> command undoes changes by " dongsheng@627: "<emphasis>adding</emphasis> history, not by modifying or erasing it. It's " dongsheng@627: "the right tool to use if you're fixing bugs, but not if you're trying to undo " dongsheng@627: "some change that has catastrophic consequences. To deal with those, see " dongsheng@627: "section <xref linkend=\"sec.undo.aaaiiieee\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:312 dongsheng@627: msgid "Backing out a changeset" dongsheng@635: msgstr "恢复一个修改集" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:314 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg backout</command> command lets you " dongsheng@627: "<quote>undo</quote> the effects of an entire changeset in an automated " dongsheng@627: "fashion. Because Mercurial's history is immutable, this command " dongsheng@627: "<emphasis>does not</emphasis> get rid of the changeset you want to undo. " dongsheng@627: "Instead, it creates a new changeset that <emphasis>reverses</emphasis> the " dongsheng@627: "effect of the to-be-undone changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:323 dongsheng@627: msgid "" dongsheng@627: "The operation of the <command role=\"hg-cmd\">hg backout</command> command is " dongsheng@627: "a little intricate, so let's illustrate it with some examples. First, we'll " dongsheng@627: "create a repository with some simple changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:330 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg backout</command> command takes a single " dongsheng@627: "changeset ID as its argument; this is the changeset to back out. Normally, " dongsheng@627: "<command role=\"hg-cmd\">hg backout</command> will drop you into a text " dongsheng@627: "editor to write a commit message, so you can record why you're backing the " dongsheng@627: "change out. In this example, we provide a commit message on the command line " dongsheng@627: "using the <option role=\"hg-opt-backout\">-m</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:341 dongsheng@627: msgid "Backing out the tip changeset" dongsheng@635: msgstr "恢复顶点修改集" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:343 dongsheng@627: msgid "We're going to start by backing out the last changeset we committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:348 dongsheng@627: msgid "" dongsheng@627: "You can see that the second line from <filename>myfile</filename> is no " dongsheng@627: "longer present. Taking a look at the output of <command role=\"hg-cmd\">hg " dongsheng@627: "log</command> gives us an idea of what the <command role=\"hg-cmd\">hg " dongsheng@627: "backout</command> command has done. &interaction.backout.simple.log; Notice " dongsheng@627: "that the new changeset that <command role=\"hg-cmd\">hg backout</command> has " dongsheng@627: "created is a child of the changeset we backed out. It's easier to see this " dongsheng@627: "in figure <xref linkend=\"fig.undo.backout\"/>, which presents a graphical " dongsheng@627: "view of the change history. As you can see, the history is nice and linear." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch09-undo.xml:362 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/undo-simple.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch09-undo.xml:364 ../en/ch09-undo.xml:477 dongsheng@627: msgid "" dongsheng@627: "Backing out a change using the <command role=\"hg-cmd\">hg backout</command> " dongsheng@627: "command" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:373 dongsheng@627: msgid "Backing out a non-tip change" dongsheng@635: msgstr "恢复非顶点的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:375 dongsheng@627: msgid "" dongsheng@627: "If you want to back out a change other than the last one you committed, pass " dongsheng@627: "the <option role=\"hg-opt-backout\">--merge</option> option to the <command " dongsheng@627: "role=\"hg-cmd\">hg backout</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:382 dongsheng@627: msgid "" dongsheng@627: "This makes backing out any changeset a <quote>one-shot</quote> operation " dongsheng@627: "that's usually simple and fast." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:388 dongsheng@627: msgid "" dongsheng@627: "If you take a look at the contents of <filename>myfile</filename> after the " dongsheng@627: "backout finishes, you'll see that the first and third changes are present, " dongsheng@627: "but not the second." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:395 dongsheng@627: msgid "" dongsheng@627: "As the graphical history in figure <xref linkend=\"fig.undo.backout-non-tip\"/" dongsheng@627: "> illustrates, Mercurial actually commits <emphasis>two</emphasis> changes in " dongsheng@627: "this kind of situation (the box-shaped nodes are the ones that Mercurial " dongsheng@627: "commits automatically). Before Mercurial begins the backout process, it " dongsheng@627: "first remembers what the current parent of the working directory is. It then " dongsheng@627: "backs out the target changeset, and commits that as a changeset. Finally, it " dongsheng@627: "merges back to the previous parent of the working directory, and commits the " dongsheng@627: "result of the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:406 dongsheng@627: msgid "" dongsheng@627: "% TODO: to me it looks like mercurial doesn't commit the second merge " dongsheng@627: "automatically!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch09-undo.xml:410 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/undo-non-tip.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch09-undo.xml:412 dongsheng@627: msgid "" dongsheng@627: "Automated backout of a non-tip change using the <command role=\"hg-cmd\">hg " dongsheng@627: "backout</command> command" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:418 dongsheng@627: msgid "" dongsheng@627: "The result is that you end up <quote>back where you were</quote>, only with " dongsheng@627: "some extra history that undoes the effect of the changeset you wanted to back " dongsheng@627: "out." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch09-undo.xml:423 dongsheng@627: msgid "Always use the <option role=\"hg-opt-backout\">--merge</option> option" dongsheng@635: msgstr "始终使用选项 <option role=\"hg-opt-backout\">--merge</option>" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch09-undo.xml:426 dongsheng@627: msgid "" dongsheng@627: "In fact, since the <option role=\"hg-opt-backout\">--merge</option> option " dongsheng@627: "will do the <quote>right thing</quote> whether or not the changeset you're " dongsheng@627: "backing out is the tip (i.e. it won't try to merge if it's backing out the " dongsheng@627: "tip, since there's no need), you should <emphasis>always</emphasis> use this " dongsheng@627: "option when you run the <command role=\"hg-cmd\">hg backout</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:437 dongsheng@627: msgid "Gaining more control of the backout process" dongsheng@635: msgstr "在恢复处理中获得更多控制" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:439 dongsheng@627: msgid "" dongsheng@627: "While I've recommended that you always use the <option role=\"hg-opt-backout" dongsheng@627: "\">--merge</option> option when backing out a change, the <command role=\"hg-" dongsheng@627: "cmd\">hg backout</command> command lets you decide how to merge a backout " dongsheng@627: "changeset. Taking control of the backout process by hand is something you " dongsheng@627: "will rarely need to do, but it can be useful to understand what the <command " dongsheng@627: "role=\"hg-cmd\">hg backout</command> command is doing for you automatically. " dongsheng@627: "To illustrate this, let's clone our first repository, but omit the backout " dongsheng@627: "change that it contains." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:452 dongsheng@627: msgid "" dongsheng@627: "As with our earlier example, We'll commit a third changeset, then back out " dongsheng@627: "its parent, and see what happens." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:458 dongsheng@627: msgid "" dongsheng@627: "Our new changeset is again a descendant of the changeset we backout out; it's " dongsheng@627: "thus a new head, <emphasis>not</emphasis> a descendant of the changeset that " dongsheng@627: "was the tip. The <command role=\"hg-cmd\">hg backout</command> command was " dongsheng@627: "quite explicit in telling us this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:466 dongsheng@627: msgid "" dongsheng@627: "Again, it's easier to see what has happened by looking at a graph of the " dongsheng@627: "revision history, in figure <xref linkend=\"fig.undo.backout-manual\"/>. " dongsheng@627: "This makes it clear that when we use <command role=\"hg-cmd\">hg backout</" dongsheng@627: "command> to back out a change other than the tip, Mercurial adds a new head " dongsheng@627: "to the repository (the change it committed is box-shaped)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch09-undo.xml:475 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/undo-manual.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:484 dongsheng@627: msgid "" dongsheng@627: "After the <command role=\"hg-cmd\">hg backout</command> command has " dongsheng@627: "completed, it leaves the new <quote>backout</quote> changeset as the parent " dongsheng@627: "of the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:491 dongsheng@627: msgid "Now we have two isolated sets of changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:495 dongsheng@627: msgid "" dongsheng@627: "Let's think about what we expect to see as the contents of <filename>myfile</" dongsheng@627: "filename> now. The first change should be present, because we've never " dongsheng@627: "backed it out. The second change should be missing, as that's the change we " dongsheng@627: "backed out. Since the history graph shows the third change as a separate " dongsheng@627: "head, we <emphasis>don't</emphasis> expect to see the third change present in " dongsheng@627: "<filename>myfile</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:505 dongsheng@627: msgid "" dongsheng@627: "To get the third change back into the file, we just do a normal merge of our " dongsheng@627: "two heads." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:510 dongsheng@627: msgid "" dongsheng@627: "Afterwards, the graphical history of our repository looks like figure <xref " dongsheng@627: "linkend=\"fig.undo.backout-manual-merge\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch09-undo.xml:515 dongsheng@627: msgid "" dongsheng@627: "<imageobject><imagedata fileref=\"images/undo-manual-merge.png\"/></" dongsheng@627: "imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch09-undo.xml:517 dongsheng@627: msgid "Manually merging a backout change" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:524 dongsheng@627: msgid "Why <command role=\"hg-cmd\">hg backout</command> works as it does" dongsheng@635: msgstr "<command role=\"hg-cmd\">hg backout</command> 的内幕" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:527 dongsheng@627: msgid "" dongsheng@627: "Here's a brief description of how the <command role=\"hg-cmd\">hg backout</" dongsheng@627: "command> command works." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:530 dongsheng@627: msgid "" dongsheng@627: "It ensures that the working directory is <quote>clean</quote>, i.e. that the " dongsheng@627: "output of <command role=\"hg-cmd\">hg status</command> would be empty." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:534 dongsheng@627: msgid "" dongsheng@627: "It remembers the current parent of the working directory. Let's call this " dongsheng@627: "changeset <literal>orig</literal>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:538 dongsheng@627: msgid "" dongsheng@627: "It does the equivalent of a <command role=\"hg-cmd\">hg update</command> to " dongsheng@627: "sync the working directory to the changeset you want to back out. Let's call " dongsheng@627: "this changeset <literal>backout</literal>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:543 dongsheng@627: msgid "" dongsheng@627: "It finds the parent of that changeset. Let's call that changeset " dongsheng@627: "<literal>parent</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:546 dongsheng@627: msgid "" dongsheng@627: "For each file that the <literal>backout</literal> changeset affected, it does " dongsheng@627: "the equivalent of a <command role=\"hg-cmd\">hg revert -r parent</command> on " dongsheng@627: "that file, to restore it to the contents it had before that changeset was " dongsheng@627: "committed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:553 dongsheng@627: msgid "" dongsheng@627: "It commits the result as a new changeset. This changeset has " dongsheng@627: "<literal>backout</literal> as its parent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:557 dongsheng@627: msgid "" dongsheng@627: "If you specify <option role=\"hg-opt-backout\">--merge</option> on the " dongsheng@627: "command line, it merges with <literal>orig</literal>, and commits the result " dongsheng@627: "of the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:563 dongsheng@627: msgid "" dongsheng@627: "An alternative way to implement the <command role=\"hg-cmd\">hg backout</" dongsheng@627: "command> command would be to <command role=\"hg-cmd\">hg export</command> the " dongsheng@627: "to-be-backed-out changeset as a diff, then use the <option role=\"cmd-opt-" dongsheng@627: "patch\">--reverse</option> option to the <command>patch</command> command to " dongsheng@627: "reverse the effect of the change without fiddling with the working " dongsheng@627: "directory. This sounds much simpler, but it would not work nearly as well." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:573 dongsheng@627: msgid "" dongsheng@627: "The reason that <command role=\"hg-cmd\">hg backout</command> does an update, " dongsheng@627: "a commit, a merge, and another commit is to give the merge machinery the best " dongsheng@627: "chance to do a good job when dealing with all the changes <emphasis>between</" dongsheng@627: "emphasis> the change you're backing out and the current tip." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:580 dongsheng@627: msgid "" dongsheng@627: "If you're backing out a changeset that's 100 revisions back in your project's " dongsheng@627: "history, the chances that the <command>patch</command> command will be able " dongsheng@627: "to apply a reverse diff cleanly are not good, because intervening changes are " dongsheng@627: "likely to have <quote>broken the context</quote> that <command>patch</" dongsheng@627: "command> uses to determine whether it can apply a patch (if this sounds like " dongsheng@627: "gibberish, see <xref linkend=\"sec.mq.patch\"/> for a discussion of the " dongsheng@627: "<command>patch</command> command). Also, Mercurial's merge machinery will " dongsheng@627: "handle files and directories being renamed, permission changes, and " dongsheng@627: "modifications to binary files, none of which <command>patch</command> can " dongsheng@627: "deal with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:597 dongsheng@627: msgid "Changes that should never have been" dongsheng@635: msgstr "不该发生的修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:599 dongsheng@627: msgid "" dongsheng@627: "Most of the time, the <command role=\"hg-cmd\">hg backout</command> command " dongsheng@627: "is exactly what you need if you want to undo the effects of a change. It " dongsheng@627: "leaves a permanent record of exactly what you did, both when committing the " dongsheng@627: "original changeset and when you cleaned up after it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:605 dongsheng@627: msgid "" dongsheng@627: "On rare occasions, though, you may find that you've committed a change that " dongsheng@627: "really should not be present in the repository at all. For example, it would " dongsheng@627: "be very unusual, and usually considered a mistake, to commit a software " dongsheng@627: "project's object files as well as its source files. Object files have almost " dongsheng@627: "no intrinsic value, and they're <emphasis>big</emphasis>, so they increase " dongsheng@627: "the size of the repository and the amount of time it takes to clone or pull " dongsheng@627: "changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:614 dongsheng@627: msgid "" dongsheng@627: "Before I discuss the options that you have if you commit a <quote>brown paper " dongsheng@627: "bag</quote> change (the kind that's so bad that you want to pull a brown " dongsheng@627: "paper bag over your head), let me first discuss some approaches that probably " dongsheng@627: "won't work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:619 dongsheng@627: msgid "" dongsheng@627: "Since Mercurial treats history as accumulative&emdash;every change builds on " dongsheng@627: "top of all changes that preceded it&emdash;you generally can't just make " dongsheng@627: "disastrous changes disappear. The one exception is when you've just " dongsheng@627: "committed a change, and it hasn't been pushed or pulled into another " dongsheng@627: "repository. That's when you can safely use the <command role=\"hg-cmd\">hg " dongsheng@627: "rollback</command> command, as I detailed in section <xref linkend=\"sec.undo." dongsheng@627: "rollback\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:628 dongsheng@627: msgid "" dongsheng@627: "After you've pushed a bad change to another repository, you <emphasis>could</" dongsheng@627: "emphasis> still use <command role=\"hg-cmd\">hg rollback</command> to make " dongsheng@627: "your local copy of the change disappear, but it won't have the consequences " dongsheng@627: "you want. The change will still be present in the remote repository, so it " dongsheng@627: "will reappear in your local repository the next time you pull." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:636 dongsheng@627: msgid "" dongsheng@627: "If a situation like this arises, and you know which repositories your bad " dongsheng@627: "change has propagated into, you can <emphasis>try</emphasis> to get rid of " dongsheng@627: "the changeefrom <emphasis>every</emphasis> one of those repositories. This " dongsheng@627: "is, of course, not a satisfactory solution: if you miss even a single " dongsheng@627: "repository while you're expunging, the change is still <quote>in the wild</" dongsheng@627: "quote>, and could propagate further." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:644 dongsheng@627: msgid "" dongsheng@627: "If you've committed one or more changes <emphasis>after</emphasis> the change " dongsheng@627: "that you'd like to see disappear, your options are further reduced. Mercurial " dongsheng@627: "doesn't provide a way to <quote>punch a hole</quote> in history, leaving " dongsheng@627: "changesets intact." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:650 dongsheng@627: msgid "" dongsheng@627: "XXX This needs filling out. The <literal>hg-replay</literal> script in the " dongsheng@627: "<literal>examples</literal> directory works, but doesn't handle merge " dongsheng@627: "changesets. Kind of an important omission." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:656 dongsheng@627: msgid "Protect yourself from <quote>escaped</quote> changes" dongsheng@635: msgstr "使用<quote>校验</quote>修改来保护你自己" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:659 dongsheng@627: msgid "" dongsheng@627: "If you've committed some changes to your local repository and they've been " dongsheng@627: "pushed or pulled somewhere else, this isn't necessarily a disaster. You can " dongsheng@627: "protect yourself ahead of time against some classes of bad changeset. This " dongsheng@627: "is particularly easy if your team usually pulls changes from a central " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:666 dongsheng@627: msgid "" dongsheng@627: "By configuring some hooks on that repository to validate incoming changesets " dongsheng@627: "(see chapter <xref linkend=\"chap.hook\"/>), you can automatically prevent " dongsheng@627: "some kinds of bad changeset from being pushed to the central repository at " dongsheng@627: "all. With such a configuration in place, some kinds of bad changeset will " dongsheng@627: "naturally tend to <quote>die out</quote> because they can't propagate into " dongsheng@627: "the central repository. Better yet, this happens without any need for " dongsheng@627: "explicit intervention." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:676 dongsheng@627: msgid "" dongsheng@627: "For instance, an incoming change hook that verifies that a changeset will " dongsheng@627: "actually compile can prevent people from inadvertantly <quote>breaking the " dongsheng@627: "build</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:683 dongsheng@627: msgid "Finding the source of a bug" dongsheng@635: msgstr "查找问题的根源" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:685 dongsheng@627: msgid "" dongsheng@627: "While it's all very well to be able to back out a changeset that introduced a " dongsheng@627: "bug, this requires that you know which changeset to back out. Mercurial " dongsheng@627: "provides an invaluable command, called <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command>, that helps you to automate this process and accomplish it very " dongsheng@627: "efficiently." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:692 dongsheng@627: msgid "" dongsheng@627: "The idea behind the <command role=\"hg-cmd\">hg bisect</command> command is " dongsheng@627: "that a changeset has introduced some change of behaviour that you can " dongsheng@627: "identify with a simple binary test. You don't know which piece of code " dongsheng@627: "introduced the change, but you know how to test for the presence of the bug. " dongsheng@627: "The <command role=\"hg-cmd\">hg bisect</command> command uses your test to " dongsheng@627: "direct its search for the changeset that introduced the code that caused the " dongsheng@627: "bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:701 dongsheng@627: msgid "" dongsheng@627: "Here are a few scenarios to help you understand how you might apply this " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:704 dongsheng@627: msgid "" dongsheng@627: "The most recent version of your software has a bug that you remember wasn't " dongsheng@627: "present a few weeks ago, but you don't know when it was introduced. Here, " dongsheng@627: "your binary test checks for the presence of that bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:709 dongsheng@627: msgid "" dongsheng@627: "You fixed a bug in a rush, and now it's time to close the entry in your " dongsheng@627: "team's bug database. The bug database requires a changeset ID when you close " dongsheng@627: "an entry, but you don't remember which changeset you fixed the bug in. Once " dongsheng@627: "again, your binary test checks for the presence of the bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:716 dongsheng@627: msgid "" dongsheng@627: "Your software works correctly, but runs 15% slower than the last time you " dongsheng@627: "measured it. You want to know which changeset introduced the performance " dongsheng@627: "regression. In this case, your binary test measures the performance of your " dongsheng@627: "software, to see whether it's <quote>fast</quote> or <quote>slow</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:723 dongsheng@627: msgid "" dongsheng@627: "The sizes of the components of your project that you ship exploded recently, " dongsheng@627: "and you suspect that something changed in the way you build your project." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:728 dongsheng@627: msgid "" dongsheng@627: "From these examples, it should be clear that the <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command> command is not useful only for finding the sources of bugs. " dongsheng@627: "You can use it to find any <quote>emergent property</quote> of a repository " dongsheng@627: "(anything that you can't find from a simple text search of the files in the " dongsheng@627: "tree) for which you can write a binary test." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:735 dongsheng@627: msgid "" dongsheng@627: "We'll introduce a little bit of terminology here, just to make it clear which " dongsheng@627: "parts of the search process are your responsibility, and which are " dongsheng@627: "Mercurial's. A <emphasis>test</emphasis> is something that <emphasis>you</" dongsheng@627: "emphasis> run when <command role=\"hg-cmd\">hg bisect</command> chooses a " dongsheng@627: "changeset. A <emphasis>probe</emphasis> is what <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command> runs to tell whether a revision is good. Finally, we'll use " dongsheng@627: "the word <quote>bisect</quote>, as both a noun and a verb, to stand in for " dongsheng@627: "the phrase <quote>search using the <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command> command</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:748 dongsheng@627: msgid "" dongsheng@627: "One simple way to automate the searching process would be simply to probe " dongsheng@627: "every changeset. However, this scales poorly. If it took ten minutes to " dongsheng@627: "test a single changeset, and you had 10,000 changesets in your repository, " dongsheng@627: "the exhaustive approach would take on average 35 <emphasis>days</emphasis> to " dongsheng@627: "find the changeset that introduced a bug. Even if you knew that the bug was " dongsheng@627: "introduced by one of the last 500 changesets, and limited your search to " dongsheng@627: "those, you'd still be looking at over 40 hours to find the changeset that " dongsheng@627: "introduced your bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:758 dongsheng@627: msgid "" dongsheng@627: "What the <command role=\"hg-cmd\">hg bisect</command> command does is use its " dongsheng@627: "knowledge of the <quote>shape</quote> of your project's revision history to " dongsheng@627: "perform a search in time proportional to the <emphasis>logarithm</emphasis> " dongsheng@627: "of the number of changesets to check (the kind of search it performs is " dongsheng@627: "called a dichotomic search). With this approach, searching through 10,000 " dongsheng@627: "changesets will take less than three hours, even at ten minutes per test (the " dongsheng@627: "search will require about 14 tests). Limit your search to the last hundred " dongsheng@627: "changesets, and it will take only about an hour (roughly seven tests)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch09-undo.xml:769 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg bisect</command> command is aware of the " dongsheng@627: "<quote>branchy</quote> nature of a Mercurial project's revision history, so " dongsheng@627: "it has no problems dealing with branches, merges, or multiple heads in a " dongsheng@627: "repository. It can prune entire branches of history with a single probe, " dongsheng@627: "which is how it operates so efficiently." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:777 dongsheng@627: msgid "Using the <command role=\"hg-cmd\">hg bisect</command> command" dongsheng@635: msgstr "使用命令 <command role=\"hg-cmd\">hg bisect</command>" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:780 dongsheng@627: msgid "" dongsheng@627: "Here's an example of <command role=\"hg-cmd\">hg bisect</command> in action." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch09-undo.xml:784 dongsheng@627: msgid "" dongsheng@627: "In versions 0.9.5 and earlier of Mercurial, <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command> was not a core command: it was distributed with Mercurial as " dongsheng@627: "an extension. This section describes the built-in command, not the old " dongsheng@627: "extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:791 dongsheng@627: msgid "" dongsheng@627: "Now let's create a repository, so that we can try out the <command role=\"hg-" dongsheng@627: "cmd\">hg bisect</command> command in isolation." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:797 dongsheng@627: msgid "" dongsheng@627: "We'll simulate a project that has a bug in it in a simple-minded way: create " dongsheng@627: "trivial changes in a loop, and nominate one specific change that will have " dongsheng@627: "the <quote>bug</quote>. This loop creates 35 changesets, each adding a " dongsheng@627: "single file to the repository. We'll represent our <quote>bug</quote> with a " dongsheng@627: "file that contains the text <quote>i have a gub</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:807 dongsheng@627: msgid "" dongsheng@627: "The next thing that we'd like to do is figure out how to use the <command " dongsheng@627: "role=\"hg-cmd\">hg bisect</command> command. We can use Mercurial's normal " dongsheng@627: "built-in help mechanism for this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:814 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg bisect</command> command works in steps. " dongsheng@627: "Each step proceeds as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:817 dongsheng@627: msgid "You run your binary test." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:819 dongsheng@627: msgid "" dongsheng@627: "If the test succeeded, you tell <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "by running the <command role=\"hg-cmd\">hg bisect good</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:824 dongsheng@627: msgid "" dongsheng@627: "If it failed, run the <command role=\"hg-cmd\">hg bisect bad</command> " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:828 dongsheng@627: msgid "" dongsheng@627: "The command uses your information to decide which changeset to test next." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:831 dongsheng@627: msgid "" dongsheng@627: "It updates the working directory to that changeset, and the process begins " dongsheng@627: "again." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:834 dongsheng@627: msgid "" dongsheng@627: "The process ends when <command role=\"hg-cmd\">hg bisect</command> identifies " dongsheng@627: "a unique changeset that marks the point where your test transitioned from " dongsheng@627: "<quote>succeeding</quote> to <quote>failing</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:839 dongsheng@627: msgid "" dongsheng@627: "To start the search, we must run the <command role=\"hg-cmd\">hg bisect --" dongsheng@627: "reset</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:844 dongsheng@627: msgid "" dongsheng@627: "In our case, the binary test we use is simple: we check to see if any file in " dongsheng@627: "the repository contains the string <quote>i have a gub</quote>. If it does, " dongsheng@627: "this changeset contains the change that <quote>caused the bug</quote>. By " dongsheng@627: "convention, a changeset that has the property we're searching for is " dongsheng@627: "<quote>bad</quote>, while one that doesn't is <quote>good</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:852 dongsheng@627: msgid "" dongsheng@627: "Most of the time, the revision to which the working directory is synced " dongsheng@627: "(usually the tip) already exhibits the problem introduced by the buggy " dongsheng@627: "change, so we'll mark it as <quote>bad</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:859 dongsheng@627: msgid "" dongsheng@627: "Our next task is to nominate a changeset that we know <emphasis>doesn't</" dongsheng@627: "emphasis> have the bug; the <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "command will <quote>bracket</quote> its search between the first pair of good " dongsheng@627: "and bad changesets. In our case, we know that revision 10 didn't have the " dongsheng@627: "bug. (I'll have more words about choosing the first <quote>good</quote> " dongsheng@627: "changeset later.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:869 dongsheng@627: msgid "Notice that this command printed some output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:871 dongsheng@627: msgid "" dongsheng@627: "It told us how many changesets it must consider before it can identify the " dongsheng@627: "one that introduced the bug, and how many tests that will require." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:875 dongsheng@627: msgid "" dongsheng@627: "It updated the working directory to the next changeset to test, and told us " dongsheng@627: "which changeset it's testing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:880 dongsheng@627: msgid "" dongsheng@627: "We now run our test in the working directory. We use the <command>grep</" dongsheng@627: "command> command to see if our <quote>bad</quote> file is present in the " dongsheng@627: "working directory. If it is, this revision is bad; if not, this revision is " dongsheng@627: "good. &interaction.bisect.search.step1;" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:886 dongsheng@627: msgid "" dongsheng@627: "This test looks like a perfect candidate for automation, so let's turn it " dongsheng@627: "into a shell function." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:890 dongsheng@627: msgid "" dongsheng@627: "We can now run an entire test step with a single command, <literal>mytest</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:895 dongsheng@627: msgid "A few more invocations of our canned test step command, and we're done." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:900 dongsheng@627: msgid "" dongsheng@627: "Even though we had 40 changesets to search through, the <command role=\"hg-cmd" dongsheng@627: "\">hg bisect</command> command let us find the changeset that introduced our " dongsheng@627: "<quote>bug</quote> with only five tests. Because the number of tests that " dongsheng@627: "the <command role=\"hg-cmd\">hg bisect</command> command performs grows " dongsheng@627: "logarithmically with the number of changesets to search, the advantage that " dongsheng@627: "it has over the <quote>brute force</quote> search approach increases with " dongsheng@627: "every changeset you add." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:911 dongsheng@627: msgid "Cleaning up after your search" dongsheng@635: msgstr "搜索后的清理" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:913 dongsheng@627: msgid "" dongsheng@627: "When you're finished using the <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "command in a repository, you can use the <command role=\"hg-cmd\">hg bisect " dongsheng@627: "reset</command> command to drop the information it was using to drive your " dongsheng@627: "search. The command doesn't use much space, so it doesn't matter if you " dongsheng@627: "forget to run this command. However, <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command> won't let you start a new search in that repository until you do a " dongsheng@627: "<command role=\"hg-cmd\">hg bisect reset</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch09-undo.xml:928 dongsheng@627: msgid "Tips for finding bugs effectively" dongsheng@635: msgstr "有效查找问题的技巧" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:931 dongsheng@627: msgid "Give consistent input" dongsheng@635: msgstr "给出一致的输入" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:933 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-cmd\">hg bisect</command> command requires that you " dongsheng@627: "correctly report the result of every test you perform. If you tell it that a " dongsheng@627: "test failed when it really succeeded, it <emphasis>might</emphasis> be able " dongsheng@627: "to detect the inconsistency. If it can identify an inconsistency in your " dongsheng@627: "reports, it will tell you that a particular changeset is both good and bad. " dongsheng@627: "However, it can't do this perfectly; it's about as likely to report the wrong " dongsheng@627: "changeset as the source of the bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:945 dongsheng@627: msgid "Automate as much as possible" dongsheng@635: msgstr "尽量自动" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:947 dongsheng@627: msgid "" dongsheng@627: "When I started using the <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "command, I tried a few times to run my tests by hand, on the command line. " dongsheng@627: "This is an approach that I, at least, am not suited to. After a few tries, I " dongsheng@627: "found that I was making enough mistakes that I was having to restart my " dongsheng@627: "searches several times before finally getting correct results." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:955 dongsheng@627: msgid "" dongsheng@627: "My initial problems with driving the <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command> command by hand occurred even with simple searches on small " dongsheng@627: "repositories; if the problem you're looking for is more subtle, or the number " dongsheng@627: "of tests that <command role=\"hg-cmd\">hg bisect</command> must perform " dongsheng@627: "increases, the likelihood of operator error ruining the search is much " dongsheng@627: "higher. Once I started automating my tests, I had much better results." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:964 dongsheng@627: msgid "The key to automated testing is twofold:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:966 dongsheng@627: msgid "always test for the same symptom, and" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:968 dongsheng@627: msgid "" dongsheng@627: "always feed consistent input to the <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:971 dongsheng@627: msgid "" dongsheng@627: "In my tutorial example above, the <command>grep</command> command tests for " dongsheng@627: "the symptom, and the <literal>if</literal> statement takes the result of this " dongsheng@627: "check and ensures that we always feed the same input to the <command role=" dongsheng@627: "\"hg-cmd\">hg bisect</command> command. The <literal>mytest</literal> " dongsheng@627: "function marries these together in a reproducible way, so that every test is " dongsheng@627: "uniform and consistent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:981 dongsheng@627: msgid "Check your results" dongsheng@635: msgstr "检查你的结果" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:983 dongsheng@627: msgid "" dongsheng@627: "Because the output of a <command role=\"hg-cmd\">hg bisect</command> search " dongsheng@627: "is only as good as the input you give it, don't take the changeset it reports " dongsheng@627: "as the absolute truth. A simple way to cross-check its report is to manually " dongsheng@627: "run your test at each of the following changesets:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:989 dongsheng@627: msgid "" dongsheng@627: "The changeset that it reports as the first bad revision. Your test should " dongsheng@627: "still report this as bad." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:993 dongsheng@627: msgid "" dongsheng@627: "The parent of that changeset (either parent, if it's a merge). Your test " dongsheng@627: "should report this changeset as good." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch09-undo.xml:997 dongsheng@627: msgid "" dongsheng@627: "A child of that changeset. Your test should report this changeset as bad." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:1003 dongsheng@627: msgid "Beware interference between bugs" dongsheng@635: msgstr "谨防问题之间的冲突" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1005 dongsheng@627: msgid "" dongsheng@627: "It's possible that your search for one bug could be disrupted by the presence " dongsheng@627: "of another. For example, let's say your software crashes at revision 100, " dongsheng@627: "and worked correctly at revision 50. Unknown to you, someone else introduced " dongsheng@627: "a different crashing bug at revision 60, and fixed it at revision 80. This " dongsheng@627: "could distort your results in one of several ways." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1013 dongsheng@627: msgid "" dongsheng@627: "It is possible that this other bug completely <quote>masks</quote> yours, " dongsheng@627: "which is to say that it occurs before your bug has a chance to manifest " dongsheng@627: "itself. If you can't avoid that other bug (for example, it prevents your " dongsheng@627: "project from building), and so can't tell whether your bug is present in a " dongsheng@627: "particular changeset, the <command role=\"hg-cmd\">hg bisect</command> " dongsheng@627: "command cannot help you directly. Instead, you can mark a changeset as " dongsheng@627: "untested by running <command role=\"hg-cmd\">hg bisect --skip</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1023 dongsheng@627: msgid "" dongsheng@627: "A different problem could arise if your test for a bug's presence is not " dongsheng@627: "specific enough. If you check for <quote>my program crashes</quote>, then " dongsheng@627: "both your crashing bug and an unrelated crashing bug that masks it will look " dongsheng@627: "like the same thing, and mislead <command role=\"hg-cmd\">hg bisect</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1030 dongsheng@627: msgid "" dongsheng@627: "Another useful situation in which to use <command role=\"hg-cmd\">hg bisect --" dongsheng@627: "skip</command> is if you can't test a revision because your project was in a " dongsheng@627: "broken and hence untestable state at that revision, perhaps because someone " dongsheng@627: "checked in a change that prevented the project from building." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch09-undo.xml:1039 dongsheng@627: msgid "Bracket your search lazily" dongsheng@635: msgstr "减少你的查找工作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1041 dongsheng@627: msgid "" dongsheng@627: "Choosing the first <quote>good</quote> and <quote>bad</quote> changesets that " dongsheng@627: "will mark the end points of your search is often easy, but it bears a little " dongsheng@627: "discussion nevertheless. From the perspective of <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command>, the <quote>newest</quote> changeset is conventionally " dongsheng@627: "<quote>bad</quote>, and the older changeset is <quote>good</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1049 dongsheng@627: msgid "" dongsheng@627: "If you're having trouble remembering when a suitable <quote>good</quote> " dongsheng@627: "change was, so that you can tell <command role=\"hg-cmd\">hg bisect</" dongsheng@627: "command>, you could do worse than testing changesets at random. Just " dongsheng@627: "remember to eliminate contenders that can't possibly exhibit the bug (perhaps " dongsheng@627: "because the feature with the bug isn't present yet) and those where another " dongsheng@627: "problem masks the bug (as I discussed above)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch09-undo.xml:1058 dongsheng@627: msgid "" dongsheng@627: "Even if you end up <quote>early</quote> by thousands of changesets or months " dongsheng@627: "of history, you will only add a handful of tests to the total number that " dongsheng@627: "<command role=\"hg-cmd\">hg bisect</command> must perform, thanks to its " dongsheng@627: "logarithmic behaviour." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch10-hook.xml:5 dongsheng@627: msgid "Handling repository events with hooks" dongsheng@627: msgstr "使用钩子处理版本库事件" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch10-hook.xml:7 dongsheng@627: msgid "" dongsheng@627: "Mercurial offers a powerful mechanism to let you perform automated actions in " dongsheng@627: "response to events that occur in a repository. In some cases, you can even " dongsheng@627: "control Mercurial's response to those events." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch10-hook.xml:12 dongsheng@627: msgid "" dongsheng@627: "The name Mercurial uses for one of these actions is a <emphasis>hook</" dongsheng@627: "emphasis>. Hooks are called <quote>triggers</quote> in some revision control " dongsheng@627: "systems, but the two names refer to the same idea." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:18 dongsheng@627: msgid "An overview of hooks in Mercurial" dongsheng@635: msgstr "Mercurial 钩子概述" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:20 dongsheng@627: msgid "" dongsheng@627: "Here is a brief list of the hooks that Mercurial supports. We will revisit " dongsheng@627: "each of these hooks in more detail later, in section <xref linkend=\"sec.hook." dongsheng@627: "ref\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:25 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">changegroup</literal>: This is run after a group of " dongsheng@627: "changesets has been brought into the repository from elsewhere." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:29 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">commit</literal>: This is run after a new changeset " dongsheng@627: "has been created in the local repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:33 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">incoming</literal>: This is run once for each new " dongsheng@627: "changeset that is brought into the repository from elsewhere. Notice the " dongsheng@627: "difference from <literal role=\"hook\">changegroup</literal>, which is run " dongsheng@627: "once per <emphasis>group</emphasis> of changesets brought in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:40 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">outgoing</literal>: This is run after a group of " dongsheng@627: "changesets has been transmitted from this repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:44 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">prechangegroup</literal>: This is run before starting " dongsheng@627: "to bring a group of changesets into the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:49 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">precommit</literal>: Controlling. This is run before " dongsheng@627: "starting a commit." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:53 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">preoutgoing</literal>: Controlling. This is run before " dongsheng@627: "starting to transmit a group of changesets from this repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:58 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretag</literal>: Controlling. This is run before " dongsheng@627: "creating a tag." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:62 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretxnchangegroup</literal>: Controlling. This is run " dongsheng@627: "after a group of changesets has been brought into the local repository from " dongsheng@627: "another, but before the transaction completes that will make the changes " dongsheng@627: "permanent in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:70 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretxncommit</literal>: Controlling. This is run after " dongsheng@627: "a new changeset has been created in the local repository, but before the " dongsheng@627: "transaction completes that will make it permanent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:76 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">preupdate</literal>: Controlling. This is run before " dongsheng@627: "starting an update or merge of the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:81 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">tag</literal>: This is run after a tag is created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:85 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">update</literal>: This is run after an update or merge " dongsheng@627: "of the working directory has finished." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:90 dongsheng@627: msgid "" dongsheng@627: "Each of the hooks whose description begins with the word <quote>Controlling</" dongsheng@627: "quote> has the ability to determine whether an activity can proceed. If the " dongsheng@627: "hook succeeds, the activity may proceed; if it fails, the activity is either " dongsheng@627: "not permitted or undone, depending on the hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:99 dongsheng@627: msgid "Hooks and security" dongsheng@635: msgstr "钩子与安全性" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:102 dongsheng@627: msgid "Hooks are run with your privileges" dongsheng@635: msgstr "钩子以你的特权执行" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:104 dongsheng@627: msgid "" dongsheng@627: "When you run a Mercurial command in a repository, and the command causes a " dongsheng@627: "hook to run, that hook runs on <emphasis>your</emphasis> system, under " dongsheng@627: "<emphasis>your</emphasis> user account, with <emphasis>your</emphasis> " dongsheng@627: "privilege level. Since hooks are arbitrary pieces of executable code, you " dongsheng@627: "should treat them with an appropriate level of suspicion. Do not install a " dongsheng@627: "hook unless you are confident that you know who created it and what it does." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:115 dongsheng@627: msgid "" dongsheng@627: "In some cases, you may be exposed to hooks that you did not install " dongsheng@627: "yourself. If you work with Mercurial on an unfamiliar system, Mercurial will " dongsheng@627: "run hooks defined in that system's global <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>\\ file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:122 dongsheng@627: msgid "" dongsheng@627: "If you are working with a repository owned by another user, Mercurial can run " dongsheng@627: "hooks defined in that user's repository, but it will still run them as " dongsheng@627: "<quote>you</quote>. For example, if you <command role=\"hg-cmd\">hg pull</" dongsheng@627: "command> from that repository, and its <filename role=\"special\">.hg/hgrc</" dongsheng@627: "filename> defines a local <literal role=\"hook\">outgoing</literal> hook, " dongsheng@627: "that hook will run under your user account, even though you don't own that " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch10-hook.xml:134 dongsheng@627: msgid "" dongsheng@627: "This only applies if you are pulling from a repository on a local or network " dongsheng@627: "filesystem. If you're pulling over http or ssh, any <literal role=\"hook" dongsheng@627: "\">outgoing</literal> hook will run under whatever account is executing the " dongsheng@627: "server process, on the server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:142 dongsheng@627: msgid "" dongsheng@627: "XXX To see what hooks are defined in a repository, use the <command role=\"hg-" dongsheng@627: "cmd\">hg config hooks</command> command. If you are working in one " dongsheng@627: "repository, but talking to another that you do not own (e.g. using <command " dongsheng@627: "role=\"hg-cmd\">hg pull</command> or <command role=\"hg-cmd\">hg incoming</" dongsheng@627: "command>), remember that it is the other repository's hooks you should be " dongsheng@627: "checking, not your own." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:153 dongsheng@627: msgid "Hooks do not propagate" dongsheng@635: msgstr "钩子不会传播" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:155 dongsheng@627: msgid "" dongsheng@627: "In Mercurial, hooks are not revision controlled, and do not propagate when " dongsheng@627: "you clone, or pull from, a repository. The reason for this is simple: a hook " dongsheng@627: "is a completely arbitrary piece of executable code. It runs under your user " dongsheng@627: "identity, with your privilege level, on your machine." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:162 dongsheng@627: msgid "" dongsheng@627: "It would be extremely reckless for any distributed revision control system to " dongsheng@627: "implement revision-controlled hooks, as this would offer an easily " dongsheng@627: "exploitable way to subvert the accounts of users of the revision control " dongsheng@627: "system." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:168 dongsheng@627: msgid "" dongsheng@627: "Since Mercurial does not propagate hooks, if you are collaborating with other " dongsheng@627: "people on a common project, you should not assume that they are using the " dongsheng@627: "same Mercurial hooks as you are, or that theirs are correctly configured. " dongsheng@627: "You should document the hooks you expect people to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:175 dongsheng@627: msgid "" dongsheng@627: "In a corporate intranet, this is somewhat easier to control, as you can for " dongsheng@627: "example provide a <quote>standard</quote> installation of Mercurial on an NFS " dongsheng@627: "filesystem, and use a site-wide <filename role=\"special\"> /.hgrc</filename>" dongsheng@627: "\\ file to define hooks that all users will see. However, this too has its " dongsheng@627: "limits; see below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:185 dongsheng@627: msgid "Hooks can be overridden" dongsheng@635: msgstr "钩子可以被覆盖" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:187 dongsheng@627: msgid "" dongsheng@627: "Mercurial allows you to override a hook definition by redefining the hook. " dongsheng@627: "You can disable it by setting its value to the empty string, or change its " dongsheng@627: "behaviour as you wish." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:192 dongsheng@627: msgid "" dongsheng@627: "If you deploy a system- or site-wide <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>\\ file that defines some hooks, you should thus understand that " dongsheng@627: "your users can disable or override those hooks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:200 dongsheng@627: msgid "Ensuring that critical hooks are run" dongsheng@635: msgstr "确保关键钩子的执行" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:202 dongsheng@627: msgid "" dongsheng@627: "Sometimes you may want to enforce a policy that you do not want others to be " dongsheng@627: "able to work around. For example, you may have a requirement that every " dongsheng@627: "changeset must pass a rigorous set of tests. Defining this requirement via a " dongsheng@627: "hook in a site-wide <filename role=\"special\"> /.hgrc</filename>\\ won't " dongsheng@627: "work for remote users on laptops, and of course local users can subvert it at " dongsheng@627: "will by overriding the hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:211 dongsheng@627: msgid "" dongsheng@627: "Instead, you can set up your policies for use of Mercurial so that people are " dongsheng@627: "expected to propagate changes through a well-known <quote>canonical</quote> " dongsheng@627: "server that you have locked down and configured appropriately." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:217 dongsheng@627: msgid "" dongsheng@627: "One way to do this is via a combination of social engineering and " dongsheng@627: "technology. Set up a restricted-access account; users can push changes over " dongsheng@627: "the network to repositories managed by this account, but they cannot log into " dongsheng@627: "the account and run normal shell commands. In this scenario, a user can " dongsheng@627: "commit a changeset that contains any old garbage they want." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:226 dongsheng@627: msgid "" dongsheng@627: "When someone pushes a changeset to the server that everyone pulls from, the " dongsheng@627: "server will test the changeset before it accepts it as permanent, and reject " dongsheng@627: "it if it fails to pass the test suite. If people only pull changes from this " dongsheng@627: "filtering server, it will serve to ensure that all changes that people pull " dongsheng@627: "have been automatically vetted." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:237 dongsheng@627: msgid "Care with <literal>pretxn</literal> hooks in a shared-access repository" dongsheng@635: msgstr "在共享版本库中注意 <literal>pretxn</literal> 钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:240 dongsheng@627: msgid "" dongsheng@627: "If you want to use hooks to do some automated work in a repository that a " dongsheng@627: "number of people have shared access to, you need to be careful in how you do " dongsheng@627: "this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:245 dongsheng@627: msgid "" dongsheng@627: "Mercurial only locks a repository when it is writing to the repository, and " dongsheng@627: "only the parts of Mercurial that write to the repository pay attention to " dongsheng@627: "locks. Write locks are necessary to prevent multiple simultaneous writers " dongsheng@627: "from scribbling on each other's work, corrupting the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:252 dongsheng@627: msgid "" dongsheng@627: "Because Mercurial is careful with the order in which it reads and writes " dongsheng@627: "data, it does not need to acquire a lock when it wants to read data from the " dongsheng@627: "repository. The parts of Mercurial that read from the repository never pay " dongsheng@627: "attention to locks. This lockless reading scheme greatly increases " dongsheng@627: "performance and concurrency." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:260 dongsheng@627: msgid "" dongsheng@627: "With great performance comes a trade-off, though, one which has the potential " dongsheng@627: "to cause you trouble unless you're aware of it. To describe this requires a " dongsheng@627: "little detail about how Mercurial adds changesets to a repository and reads " dongsheng@627: "those changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:267 dongsheng@627: msgid "" dongsheng@627: "When Mercurial <emphasis>writes</emphasis> metadata, it writes it straight " dongsheng@627: "into the destination file. It writes file data first, then manifest data " dongsheng@627: "(which contains pointers to the new file data), then changelog data (which " dongsheng@627: "contains pointers to the new manifest data). Before the first write to each " dongsheng@627: "file, it stores a record of where the end of the file was in its transaction " dongsheng@627: "log. If the transaction must be rolled back, Mercurial simply truncates each " dongsheng@627: "file back to the size it was before the transaction began." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:278 dongsheng@627: msgid "" dongsheng@627: "When Mercurial <emphasis>reads</emphasis> metadata, it reads the changelog " dongsheng@627: "first, then everything else. Since a reader will only access parts of the " dongsheng@627: "manifest or file metadata that it can see in the changelog, it can never see " dongsheng@627: "partially written data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:284 dongsheng@627: msgid "" dongsheng@627: "Some controlling hooks (<literal role=\"hook\">pretxncommit</literal> and " dongsheng@627: "<literal role=\"hook\">pretxnchangegroup</literal>) run when a transaction is " dongsheng@627: "almost complete. All of the metadata has been written, but Mercurial can " dongsheng@627: "still roll the transaction back and cause the newly-written data to disappear." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:292 dongsheng@627: msgid "" dongsheng@627: "If one of these hooks runs for long, it opens a window of time during which a " dongsheng@627: "reader can see the metadata for changesets that are not yet permanent, and " dongsheng@627: "should not be thought of as <quote>really there</quote>. The longer the hook " dongsheng@627: "runs, the longer that window is open." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:300 dongsheng@627: msgid "The problem illustrated" dongsheng@635: msgstr "问题的演示" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:302 dongsheng@627: msgid "" dongsheng@627: "In principle, a good use for the <literal role=\"hook\">pretxnchangegroup</" dongsheng@627: "literal> hook would be to automatically build and test incoming changes " dongsheng@627: "before they are accepted into a central repository. This could let you " dongsheng@627: "guarantee that nobody can push changes to this repository that <quote>break " dongsheng@627: "the build</quote>. But if a client can pull changes while they're being " dongsheng@627: "tested, the usefulness of the test is zero; an unsuspecting someone can pull " dongsheng@627: "untested changes, potentially breaking their build." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:313 dongsheng@627: msgid "" dongsheng@627: "The safest technological answer to this challenge is to set up such a " dongsheng@627: "<quote>gatekeeper</quote> repository as <emphasis>unidirectional</emphasis>. " dongsheng@627: "Let it take changes pushed in from the outside, but do not allow anyone to " dongsheng@627: "pull changes from it (use the <literal role=\"hook\">preoutgoing</literal> " dongsheng@627: "hook to lock it down). Configure a <literal role=\"hook\">changegroup</" dongsheng@627: "literal> hook so that if a build or test succeeds, the hook will push the new " dongsheng@627: "changes out to another repository that people <emphasis>can</emphasis> pull " dongsheng@627: "from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:325 dongsheng@627: msgid "" dongsheng@627: "In practice, putting a centralised bottleneck like this in place is not often " dongsheng@627: "a good idea, and transaction visibility has nothing to do with the problem. " dongsheng@627: "As the size of a project&emdash;and the time it takes to build and " dongsheng@627: "test&emdash;grows, you rapidly run into a wall with this <quote>try before " dongsheng@627: "you buy</quote> approach, where you have more changesets to test than time in " dongsheng@627: "which to deal with them. The inevitable result is frustration on the part of " dongsheng@627: "all involved." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:336 dongsheng@627: msgid "" dongsheng@627: "An approach that scales better is to get people to build and test before they " dongsheng@627: "push, then run automated builds and tests centrally <emphasis>after</" dongsheng@627: "emphasis> a push, to be sure all is well. The advantage of this approach is " dongsheng@627: "that it does not impose a limit on the rate at which the repository can " dongsheng@627: "accept changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:347 dongsheng@627: msgid "A short tutorial on using hooks" dongsheng@635: msgstr "使用钩子的简短指南" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:349 dongsheng@627: msgid "" dongsheng@627: "It is easy to write a Mercurial hook. Let's start with a hook that runs when " dongsheng@627: "you finish a <command role=\"hg-cmd\">hg commit</command>, and simply prints " dongsheng@627: "the hash of the changeset you just created. The hook is called <literal role=" dongsheng@627: "\"hook\">commit</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:356 dongsheng@627: msgid "All hooks follow the pattern in this example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:360 dongsheng@627: msgid "" dongsheng@627: "You add an entry to the <literal role=\"rc-hooks\">hooks</literal> section of " dongsheng@627: "your <filename role=\"special\"> /.hgrc</filename>. On the left is the name " dongsheng@627: "of the event to trigger on; on the right is the action to take. As you can " dongsheng@627: "see, you can run an arbitrary shell command in a hook. Mercurial passes " dongsheng@627: "extra information to the hook using environment variables (look for " dongsheng@627: "<envar>HG_NODE</envar> in the example)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:370 dongsheng@627: msgid "Performing multiple actions per event" dongsheng@635: msgstr "每个事件执行多个操作" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:372 dongsheng@627: msgid "" dongsheng@627: "Quite often, you will want to define more than one hook for a particular kind " dongsheng@627: "of event, as shown below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:377 dongsheng@627: msgid "" dongsheng@627: "Mercurial lets you do this by adding an <emphasis>extension</emphasis> to the " dongsheng@627: "end of a hook's name. You extend a hook's name by giving the name of the " dongsheng@627: "hook, followed by a full stop (the <quote><literal>.</literal></quote> " dongsheng@627: "character), followed by some more text of your choosing. For example, " dongsheng@627: "Mercurial will run both <literal>commit.foo</literal> and <literal>commit." dongsheng@627: "bar</literal> when the <literal>commit</literal> event occurs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:388 dongsheng@627: msgid "" dongsheng@627: "To give a well-defined order of execution when there are multiple hooks " dongsheng@627: "defined for an event, Mercurial sorts hooks by extension, and executes the " dongsheng@627: "hook commands in this sorted order. In the above example, it will execute " dongsheng@627: "<literal>commit.bar</literal> before <literal>commit.foo</literal>, and " dongsheng@627: "<literal>commit</literal> before both." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:397 dongsheng@627: msgid "" dongsheng@627: "It is a good idea to use a somewhat descriptive extension when you define a " dongsheng@627: "new hook. This will help you to remember what the hook was for. If the hook " dongsheng@627: "fails, you'll get an error message that contains the hook name and extension, " dongsheng@627: "so using a descriptive extension could give you an immediate hint as to why " dongsheng@627: "the hook failed (see section <xref linkend=\"sec.hook.perm\"/> for an " dongsheng@627: "example)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:408 dongsheng@627: msgid "Controlling whether an activity can proceed" dongsheng@635: msgstr "控制处理的活动" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:410 dongsheng@627: msgid "" dongsheng@627: "In our earlier examples, we used the <literal role=\"hook\">commit</literal> " dongsheng@627: "hook, which is run after a commit has completed. This is one of several " dongsheng@627: "Mercurial hooks that run after an activity finishes. Such hooks have no way " dongsheng@627: "of influencing the activity itself." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:417 dongsheng@627: msgid "" dongsheng@627: "Mercurial defines a number of events that occur before an activity starts; or " dongsheng@627: "after it starts, but before it finishes. Hooks that trigger on these events " dongsheng@627: "have the added ability to choose whether the activity can continue, or will " dongsheng@627: "abort." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:423 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hook\">pretxncommit</literal> hook runs after a commit " dongsheng@627: "has all but completed. In other words, the metadata representing the " dongsheng@627: "changeset has been written out to disk, but the transaction has not yet been " dongsheng@627: "allowed to complete. The <literal role=\"hook\">pretxncommit</literal> hook " dongsheng@627: "has the ability to decide whether the transaction can complete, or must be " dongsheng@627: "rolled back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:432 dongsheng@627: msgid "" dongsheng@627: "If the <literal role=\"hook\">pretxncommit</literal> hook exits with a status " dongsheng@627: "code of zero, the transaction is allowed to complete; the commit finishes; " dongsheng@627: "and the <literal role=\"hook\">commit</literal> hook is run. If the <literal " dongsheng@627: "role=\"hook\">pretxncommit</literal> hook exits with a non-zero status code, " dongsheng@627: "the transaction is rolled back; the metadata representing the changeset is " dongsheng@627: "erased; and the <literal role=\"hook\">commit</literal> hook is not run." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:444 dongsheng@627: msgid "" dongsheng@627: "The hook in the example above checks that a commit comment contains a bug " dongsheng@627: "ID. If it does, the commit can complete. If not, the commit is rolled back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:452 dongsheng@627: msgid "Writing your own hooks" dongsheng@635: msgstr "编写钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:454 dongsheng@627: msgid "" dongsheng@627: "When you are writing a hook, you might find it useful to run Mercurial either " dongsheng@627: "with the <option role=\"hg-opt-global\">-v</option> option, or the <envar " dongsheng@627: "role=\"rc-item-ui\">verbose</envar> config item set to <quote>true</quote>. " dongsheng@627: "When you do so, Mercurial will print a message before it calls each hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:463 dongsheng@627: msgid "Choosing how your hook should run" dongsheng@635: msgstr "选择钩子的执行方式" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:465 dongsheng@627: msgid "" dongsheng@627: "You can write a hook either as a normal program&emdash;typically a shell " dongsheng@627: "script&emdash;or as a Python function that is executed within the Mercurial " dongsheng@627: "process." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:470 dongsheng@627: msgid "" dongsheng@627: "Writing a hook as an external program has the advantage that it requires no " dongsheng@627: "knowledge of Mercurial's internals. You can call normal Mercurial commands " dongsheng@627: "to get any added information you need. The trade-off is that external hooks " dongsheng@627: "are slower than in-process hooks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:477 dongsheng@627: msgid "" dongsheng@627: "An in-process Python hook has complete access to the Mercurial API, and does " dongsheng@627: "not <quote>shell out</quote> to another process, so it is inherently faster " dongsheng@627: "than an external hook. It is also easier to obtain much of the information " dongsheng@627: "that a hook requires by using the Mercurial API than by running Mercurial " dongsheng@627: "commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:485 dongsheng@627: msgid "" dongsheng@627: "If you are comfortable with Python, or require high performance, writing your " dongsheng@627: "hooks in Python may be a good choice. However, when you have a " dongsheng@627: "straightforward hook to write and you don't need to care about performance " dongsheng@627: "(probably the majority of hooks), a shell script is perfectly fine." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:494 dongsheng@627: msgid "Hook parameters" dongsheng@635: msgstr "钩子的参数" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:496 dongsheng@627: msgid "" dongsheng@627: "Mercurial calls each hook with a set of well-defined parameters. In Python, " dongsheng@627: "a parameter is passed as a keyword argument to your hook function. For an " dongsheng@627: "external program, a parameter is passed as an environment variable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:502 dongsheng@627: msgid "" dongsheng@627: "Whether your hook is written in Python or as a shell script, the hook-" dongsheng@627: "specific parameter names and values will be the same. A boolean parameter " dongsheng@627: "will be represented as a boolean value in Python, but as the number 1 (for " dongsheng@627: "<quote>true</quote>) or 0 (for <quote>false</quote>) as an environment " dongsheng@627: "variable for an external hook. If a hook parameter is named <literal>foo</" dongsheng@627: "literal>, the keyword argument for a Python hook will also be named " dongsheng@627: "<literal>foo</literal>, while the environment variable for an external hook " dongsheng@627: "will be named <literal>HG_FOO</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:516 dongsheng@627: msgid "Hook return values and activity control" dongsheng@635: msgstr "钩子的返回值与活动控制" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:518 dongsheng@627: msgid "" dongsheng@627: "A hook that executes successfully must exit with a status of zero if " dongsheng@627: "external, or return boolean <quote>false</quote> if in-process. Failure is " dongsheng@627: "indicated with a non-zero exit status from an external hook, or an in-process " dongsheng@627: "hook returning boolean <quote>true</quote>. If an in-process hook raises an " dongsheng@627: "exception, the hook is considered to have failed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:526 dongsheng@627: msgid "" dongsheng@627: "For a hook that controls whether an activity can proceed, zero/false means " dongsheng@627: "<quote>allow</quote>, while non-zero/true/exception means <quote>deny</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:533 dongsheng@627: msgid "Writing an external hook" dongsheng@635: msgstr "编写外部钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:535 dongsheng@627: msgid "" dongsheng@627: "When you define an external hook in your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>\\ and the hook is run, its value is passed to your shell, which " dongsheng@627: "interprets it. This means that you can use normal shell constructs in the " dongsheng@627: "body of the hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:542 dongsheng@627: msgid "" dongsheng@627: "An executable hook is always run with its current directory set to a " dongsheng@627: "repository's root directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:546 dongsheng@627: msgid "" dongsheng@627: "Each hook parameter is passed in as an environment variable; the name is " dongsheng@627: "upper-cased, and prefixed with the string <quote><literal>HG_</literal></" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:551 dongsheng@627: msgid "" dongsheng@627: "With the exception of hook parameters, Mercurial does not set or modify any " dongsheng@627: "environment variables when running a hook. This is useful to remember if you " dongsheng@627: "are writing a site-wide hook that may be run by a number of different users " dongsheng@627: "with differing environment variables set. In multi-user situations, you " dongsheng@627: "should not rely on environment variables being set to the values you have in " dongsheng@627: "your environment when testing the hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:562 dongsheng@627: msgid "Telling Mercurial to use an in-process hook" dongsheng@635: msgstr "让 MercurialMercurial 使用进程内钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:564 dongsheng@627: msgid "" dongsheng@627: "The <filename role=\"special\"> /.hgrc</filename>\\ syntax for defining an in-" dongsheng@627: "process hook is slightly different than for an executable hook. The value of " dongsheng@627: "the hook must start with the text <quote><literal>python:</literal></quote>, " dongsheng@627: "and continue with the fully-qualified name of a callable object to use as the " dongsheng@627: "hook's value." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:572 dongsheng@627: msgid "" dongsheng@627: "The module in which a hook lives is automatically imported when a hook is " dongsheng@627: "run. So long as you have the module name and <envar>PYTHONPATH</envar> " dongsheng@627: "right, it should <quote>just work</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:578 dongsheng@627: msgid "" dongsheng@627: "The following <filename role=\"special\"> /.hgrc</filename>\\ example snippet " dongsheng@627: "illustrates the syntax and meaning of the notions we just described." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:584 dongsheng@627: msgid "" dongsheng@627: "When Mercurial runs the <literal>commit.example</literal> hook, it imports " dongsheng@627: "<literal>mymodule.submodule</literal>, looks for the callable object named " dongsheng@627: "<literal>myhook</literal>, and calls it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:592 dongsheng@627: msgid "Writing an in-process hook" dongsheng@635: msgstr "编写进程内钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:594 dongsheng@627: msgid "" dongsheng@627: "The simplest in-process hook does nothing, but illustrates the basic shape of " dongsheng@627: "the hook API:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:599 dongsheng@627: msgid "" dongsheng@627: "The first argument to a Python hook is always a <literal role=\"py-mod-" dongsheng@627: "mercurial.ui\">ui</literal> object. The second is a repository object; at " dongsheng@627: "the moment, it is always an instance of <literal role=\"py-mod-mercurial." dongsheng@627: "localrepo\">localrepository</literal>. Following these two arguments are " dongsheng@627: "other keyword arguments. Which ones are passed in depends on the hook being " dongsheng@627: "called, but a hook can ignore arguments it doesn't care about by dropping " dongsheng@627: "them into a keyword argument dict, as with <literal>**kwargs</literal> above." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:614 dongsheng@627: msgid "Some hook examples" dongsheng@635: msgstr "钩子样例" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:617 dongsheng@627: msgid "Writing meaningful commit messages" dongsheng@635: msgstr "编写有意义的提交日志" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:619 dongsheng@627: msgid "" dongsheng@627: "It's hard to imagine a useful commit message being very short. The simple " dongsheng@627: "<literal role=\"hook\">pretxncommit</literal> hook of the example below will " dongsheng@627: "prevent you from committing a changeset with a message that is less than ten " dongsheng@627: "bytes long." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:629 dongsheng@627: msgid "Checking for trailing whitespace" dongsheng@635: msgstr "检查行尾空格" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:631 dongsheng@627: msgid "" dongsheng@627: "An interesting use of a commit-related hook is to help you to write cleaner " dongsheng@627: "code. A simple example of <quote>cleaner code</quote> is the dictum that a " dongsheng@627: "change should not add any new lines of text that contain <quote>trailing " dongsheng@627: "whitespace</quote>. Trailing whitespace is a series of space and tab " dongsheng@627: "characters at the end of a line of text. In most cases, trailing whitespace " dongsheng@627: "is unnecessary, invisible noise, but it is occasionally problematic, and " dongsheng@627: "people often prefer to get rid of it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:642 dongsheng@627: msgid "" dongsheng@627: "You can use either the <literal role=\"hook\">precommit</literal> or <literal " dongsheng@627: "role=\"hook\">pretxncommit</literal> hook to tell whether you have a trailing " dongsheng@627: "whitespace problem. If you use the <literal role=\"hook\">precommit</" dongsheng@627: "literal> hook, the hook will not know which files you are committing, so it " dongsheng@627: "will have to check every modified file in the repository for trailing white " dongsheng@627: "space. If you want to commit a change to just the file <filename>foo</" dongsheng@627: "filename>, but the file <filename>bar</filename> contains trailing " dongsheng@627: "whitespace, doing a check in the <literal role=\"hook\">precommit</literal> " dongsheng@627: "hook will prevent you from committing <filename>foo</filename> due to the " dongsheng@627: "problem with <filename>bar</filename>. This doesn't seem right." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:658 dongsheng@627: msgid "" dongsheng@627: "Should you choose the <literal role=\"hook\">pretxncommit</literal> hook, the " dongsheng@627: "check won't occur until just before the transaction for the commit " dongsheng@627: "completes. This will allow you to check for problems only the exact files " dongsheng@627: "that are being committed. However, if you entered the commit message " dongsheng@627: "interactively and the hook fails, the transaction will roll back; you'll have " dongsheng@627: "to re-enter the commit message after you fix the trailing whitespace and run " dongsheng@627: "<command role=\"hg-cmd\">hg commit</command> again." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:671 dongsheng@627: msgid "" dongsheng@627: "In this example, we introduce a simple <literal role=\"hook\">pretxncommit</" dongsheng@627: "literal> hook that checks for trailing whitespace. This hook is short, but " dongsheng@627: "not very helpful. It exits with an error status if a change adds a line with " dongsheng@627: "trailing whitespace to any file, but does not print any information that " dongsheng@627: "might help us to identify the offending file or line. It also has the nice " dongsheng@627: "property of not paying attention to unmodified lines; only lines that " dongsheng@627: "introduce new trailing whitespace cause problems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:682 dongsheng@627: msgid "" dongsheng@627: "The above version is much more complex, but also more useful. It parses a " dongsheng@627: "unified diff to see if any lines add trailing whitespace, and prints the name " dongsheng@627: "of the file and the line number of each such occurrence. Even better, if the " dongsheng@627: "change adds trailing whitespace, this hook saves the commit comment and " dongsheng@627: "prints the name of the save file before exiting and telling Mercurial to roll " dongsheng@627: "the transaction back, so you can use the <option role=\"hg-opt-commit\">-l " dongsheng@627: "filename</option> option to <command role=\"hg-cmd\">hg commit</command> to " dongsheng@627: "reuse the saved commit message once you've corrected the problem." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:696 dongsheng@627: msgid "" dongsheng@627: "As a final aside, note in the example above the use of <command>perl</" dongsheng@627: "command>'s in-place editing feature to get rid of trailing whitespace from a " dongsheng@627: "file. This is concise and useful enough that I will reproduce it here." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:706 dongsheng@627: msgid "Bundled hooks" dongsheng@635: msgstr "内置的钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch10-hook.xml:708 dongsheng@627: msgid "" dongsheng@627: "Mercurial ships with several bundled hooks. You can find them in the " dongsheng@627: "<filename class=\"directory\">hgext</filename> directory of a Mercurial " dongsheng@627: "source tree. If you are using a Mercurial binary package, the hooks will be " dongsheng@627: "located in the <filename class=\"directory\">hgext</filename> directory of " dongsheng@627: "wherever your package installer put Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:717 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hg-ext\">acl</literal>&emdash;access control for parts of a " dongsheng@627: "repository" dongsheng@635: msgstr "<literal role=\"hg-ext\">acl</literal>&emdash;版本库的访问控制" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:720 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">acl</literal> extension lets you control which " dongsheng@627: "remote users are allowed to push changesets to a networked server. You can " dongsheng@627: "protect any portion of a repository (including the entire repo), so that a " dongsheng@627: "specific remote user can push changes that do not affect the protected " dongsheng@627: "portion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:728 dongsheng@627: msgid "" dongsheng@627: "This extension implements access control based on the identity of the user " dongsheng@627: "performing a push, <emphasis>not</emphasis> on who committed the changesets " dongsheng@627: "they're pushing. It makes sense to use this hook only if you have a locked-" dongsheng@627: "down server environment that authenticates remote users, and you want to be " dongsheng@627: "sure that only specific users are allowed to push changes to that server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:738 dongsheng@627: msgid "Configuring the <literal role=\"hook\">acl</literal> hook" dongsheng@635: msgstr "配置 <literal role=\"hook\">acl</literal> 钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:741 dongsheng@627: msgid "" dongsheng@627: "In order to manage incoming changesets, the <literal role=\"hg-ext\">acl</" dongsheng@627: "literal> hook must be used as a <literal role=\"hook\">pretxnchangegroup</" dongsheng@627: "literal> hook. This lets it see which files are modified by each incoming " dongsheng@627: "changeset, and roll back a group of changesets if they modify " dongsheng@627: "<quote>forbidden</quote> files. Example:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:751 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">acl</literal> extension is configured using " dongsheng@627: "three sections." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:755 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"rc-acl\">acl</literal> section has only one entry, <envar " dongsheng@627: "role=\"rc-item-acl\">sources</envar>, which lists the sources of incoming " dongsheng@627: "changesets that the hook should pay attention to. You don't normally need to " dongsheng@627: "configure this section." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:762 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-acl\">serve</envar>: Control incoming changesets that " dongsheng@627: "are arriving from a remote repository over http or ssh. This is the default " dongsheng@627: "value of <envar role=\"rc-item-acl\">sources</envar>, and usually the only " dongsheng@627: "setting you'll need for this configuration item." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:770 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-acl\">pull</envar>: Control incoming changesets that " dongsheng@627: "are arriving via a pull from a local repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:775 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-acl\">push</envar>: Control incoming changesets that " dongsheng@627: "are arriving via a push from a local repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:780 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-acl\">bundle</envar>: Control incoming changesets that " dongsheng@627: "are arriving from another repository via a bundle." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:786 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"rc-acl.allow\">acl.allow</literal> section controls the " dongsheng@627: "users that are allowed to add changesets to the repository. If this section " dongsheng@627: "is not present, all users that are not explicitly denied are allowed. If " dongsheng@627: "this section is present, all users that are not explicitly allowed are denied " dongsheng@627: "(so an empty section means that all users are denied)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:795 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"rc-acl.deny\">acl.deny</literal> section determines which " dongsheng@627: "users are denied from adding changesets to the repository. If this section " dongsheng@627: "is not present or is empty, no users are denied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:801 dongsheng@627: msgid "" dongsheng@627: "The syntaxes for the <literal role=\"rc-acl.allow\">acl.allow</literal> and " dongsheng@627: "<literal role=\"rc-acl.deny\">acl.deny</literal> sections are identical. On " dongsheng@627: "the left of each entry is a glob pattern that matches files or directories, " dongsheng@627: "relative to the root of the repository; on the right, a user name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:809 dongsheng@627: msgid "" dongsheng@627: "In the following example, the user <literal>docwriter</literal> can only push " dongsheng@627: "changes to the <filename class=\"directory\">docs</filename> subtree of the " dongsheng@627: "repository, while <literal>intern</literal> can push changes to any file or " dongsheng@627: "directory except <filename class=\"directory\">source/sensitive</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:821 ../en/ch10-hook.xml:1095 ../en/ch10-hook.xml:1308 dongsheng@627: msgid "Testing and troubleshooting" dongsheng@635: msgstr "测试与问题处理" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:823 dongsheng@627: msgid "" dongsheng@627: "If you want to test the <literal role=\"hg-ext\">acl</literal> hook, run it " dongsheng@627: "with Mercurial's debugging output enabled. Since you'll probably be running " dongsheng@627: "it on a server where it's not convenient (or sometimes possible) to pass in " dongsheng@627: "the <option role=\"hg-opt-global\">--debug</option> option, don't forget that " dongsheng@627: "you can enable debugging output in your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:833 dongsheng@627: msgid "" dongsheng@627: "With this enabled, the <literal role=\"hg-ext\">acl</literal> hook will print " dongsheng@627: "enough information to let you figure out why it is allowing or forbidding " dongsheng@627: "pushes from specific users." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:842 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hg-ext\">bugzilla</literal>&emdash;integration with Bugzilla" dongsheng@635: msgstr "<literal role=\"hg-ext\">bugzilla</literal>&emdash;与 Bugzilla 的集成" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:846 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">bugzilla</literal> extension adds a comment to a " dongsheng@627: "Bugzilla bug whenever it finds a reference to that bug ID in a commit " dongsheng@627: "comment. You can install this hook on a shared server, so that any time a " dongsheng@627: "remote user pushes changes to this server, the hook gets run." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:853 dongsheng@627: msgid "" dongsheng@627: "It adds a comment to the bug that looks like this (you can configure the " dongsheng@627: "contents of the comment&emdash;see below):" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:862 dongsheng@627: msgid "" dongsheng@627: "The value of this hook is that it automates the process of updating a bug any " dongsheng@627: "time a changeset refers to it. If you configure the hook properly, it makes " dongsheng@627: "it easy for people to browse straight from a Bugzilla bug to a changeset that " dongsheng@627: "refers to that bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:869 dongsheng@627: msgid "" dongsheng@627: "You can use the code in this hook as a starting point for some more exotic " dongsheng@627: "Bugzilla integration recipes. Here are a few possibilities:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:874 dongsheng@627: msgid "" dongsheng@627: "Require that every changeset pushed to the server have a valid bug ID in its " dongsheng@627: "commit comment. In this case, you'd want to configure the hook as a <literal " dongsheng@627: "role=\"hook\">pretxncommit</literal> hook. This would allow the hook to " dongsheng@627: "reject changes that didn't contain bug IDs." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:882 dongsheng@627: msgid "" dongsheng@627: "Allow incoming changesets to automatically modify the <emphasis>state</" dongsheng@627: "emphasis> of a bug, as well as simply adding a comment. For example, the " dongsheng@627: "hook could recognise the string <quote>fixed bug 31337</quote> as indicating " dongsheng@627: "that it should update the state of bug 31337 to <quote>requires testing</" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:892 dongsheng@627: msgid "Configuring the <literal role=\"hook\">bugzilla</literal> hook" dongsheng@635: msgstr "配置 <literal role=\"hook\">bugzilla</literal> 钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:895 dongsheng@627: msgid "" dongsheng@627: "You should configure this hook in your server's <filename role=\"special\"> /." dongsheng@627: "hgrc</filename>\\ as an <literal role=\"hook\">incoming</literal> hook, for " dongsheng@627: "example as follows:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:903 dongsheng@627: msgid "" dongsheng@627: "Because of the specialised nature of this hook, and because Bugzilla was not " dongsheng@627: "written with this kind of integration in mind, configuring this hook is a " dongsheng@627: "somewhat involved process." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:909 dongsheng@627: msgid "" dongsheng@627: "Before you begin, you must install the MySQL bindings for Python on the host" dongsheng@627: "(s) where you'll be running the hook. If this is not available as a binary " dongsheng@627: "package for your system, you can download it from <citation>web:mysql-python</" dongsheng@627: "citation>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:916 dongsheng@627: msgid "" dongsheng@627: "Configuration information for this hook lives in the <literal role=\"rc-" dongsheng@627: "bugzilla\">bugzilla</literal> section of your <filename role=\"special\"> /." dongsheng@627: "hgrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:921 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">version</envar>: The version of Bugzilla " dongsheng@627: "installed on the server. The database schema that Bugzilla uses changes " dongsheng@627: "occasionally, so this hook has to know exactly which schema to use. At the " dongsheng@627: "moment, the only version supported is <literal>2.16</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:930 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">host</envar>: The hostname of the MySQL " dongsheng@627: "server that stores your Bugzilla data. The database must be configured to " dongsheng@627: "allow connections from whatever host you are running the <literal role=\"hook" dongsheng@627: "\">bugzilla</literal> hook on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:937 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">user</envar>: The username with which to " dongsheng@627: "connect to the MySQL server. The database must be configured to allow this " dongsheng@627: "user to connect from whatever host you are running the <literal role=\"hook" dongsheng@627: "\">bugzilla</literal> hook on. This user must be able to access and modify " dongsheng@627: "Bugzilla tables. The default value of this item is <literal>bugs</literal>, " dongsheng@627: "which is the standard name of the Bugzilla user in a MySQL database." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:948 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">password</envar>: The MySQL password for the " dongsheng@627: "user you configured above. This is stored as plain text, so you should make " dongsheng@627: "sure that unauthorised users cannot read the <filename role=\"special\"> /." dongsheng@627: "hgrc</filename>\\ file where you store this information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:957 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">db</envar>: The name of the Bugzilla " dongsheng@627: "database on the MySQL server. The default value of this item is " dongsheng@627: "<literal>bugs</literal>, which is the standard name of the MySQL database " dongsheng@627: "where Bugzilla stores its data." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:964 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-bugzilla\">notify</envar>: If you want Bugzilla to send " dongsheng@627: "out a notification email to subscribers after this hook has added a comment " dongsheng@627: "to a bug, you will need this hook to run a command whenever it updates the " dongsheng@627: "database. The command to run depends on where you have installed Bugzilla, " dongsheng@627: "but it will typically look something like this, if you have Bugzilla " dongsheng@627: "installed in <filename class=\"directory\">/var/www/html/bugzilla</filename>:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:977 dongsheng@627: msgid "" dongsheng@627: "The Bugzilla <literal>processmail</literal> program expects to be given a bug " dongsheng@627: "ID (the hook replaces <quote><literal>%s</literal></quote> with the bug ID) " dongsheng@627: "and an email address. It also expects to be able to write to some files in " dongsheng@627: "the directory that it runs in. If Bugzilla and this hook are not installed " dongsheng@627: "on the same machine, you will need to find a way to run <literal>processmail</" dongsheng@627: "literal> on the server where Bugzilla is installed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:992 dongsheng@627: msgid "Mapping committer names to Bugzilla user names" dongsheng@635: msgstr "提交者的名称与 Bugzilla 用户名称的映射" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:994 dongsheng@627: msgid "" dongsheng@627: "By default, the <literal role=\"hg-ext\">bugzilla</literal> hook tries to use " dongsheng@627: "the email address of a changeset's committer as the Bugzilla user name with " dongsheng@627: "which to update a bug. If this does not suit your needs, you can map " dongsheng@627: "committer email addresses to Bugzilla user names using a <literal role=\"rc-" dongsheng@627: "usermap\">usermap</literal> section." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1003 dongsheng@627: msgid "" dongsheng@627: "Each item in the <literal role=\"rc-usermap\">usermap</literal> section " dongsheng@627: "contains an email address on the left, and a Bugzilla user name on the right." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1010 dongsheng@627: msgid "" dongsheng@627: "You can either keep the <literal role=\"rc-usermap\">usermap</literal> data " dongsheng@627: "in a normal <filename role=\"special\">~/.hgrc</filename>, or tell the " dongsheng@627: "<literal role=\"hg-ext\">bugzilla</literal> hook to read the information from " dongsheng@627: "an external <filename>usermap</filename> file. In the latter case, you can " dongsheng@627: "store <filename>usermap</filename> data by itself in (for example) a user-" dongsheng@627: "modifiable repository. This makes it possible to let your users maintain " dongsheng@627: "their own <envar role=\"rc-item-bugzilla\">usermap</envar> entries. The main " dongsheng@627: "<filename role=\"special\"> /.hgrc</filename>\\ file might look like this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1026 dongsheng@627: msgid "" dongsheng@627: "While the <filename>usermap</filename> file that it refers to might look like " dongsheng@627: "this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:1035 dongsheng@627: msgid "Configuring the text that gets added to a bug" dongsheng@635: msgstr "配置增加到问题中的正文" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1037 dongsheng@627: msgid "" dongsheng@627: "You can configure the text that this hook adds as a comment; you specify it " dongsheng@627: "in the form of a Mercurial template. Several <filename role=\"special\"> /." dongsheng@627: "hgrc</filename>\\ entries (still in the <literal role=\"rc-bugzilla" dongsheng@627: "\">bugzilla</literal> section) control this behaviour." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1044 dongsheng@627: msgid "" dongsheng@627: "<literal>strip</literal>: The number of leading path elements to strip from a " dongsheng@627: "repository's path name to construct a partial path for a URL. For example, if " dongsheng@627: "the repositories on your server live under <filename class=\"directory\">/" dongsheng@627: "home/hg/repos</filename>, and you have a repository whose path is <filename " dongsheng@627: "class=\"directory\">/home/hg/repos/app/tests</filename>, then setting " dongsheng@627: "<literal>strip</literal> to <literal>4</literal> will give a partial path of " dongsheng@627: "<filename class=\"directory\">app/tests</filename>. The hook will make this " dongsheng@627: "partial path available when expanding a template, as <literal>webroot</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1058 dongsheng@627: msgid "" dongsheng@627: "<literal>template</literal>: The text of the template to use. In addition to " dongsheng@627: "the usual changeset-related variables, this template can use <literal>hgweb</" dongsheng@627: "literal> (the value of the <literal>hgweb</literal> configuration item above) " dongsheng@627: "and <literal>webroot</literal> (the path constructed using <literal>strip</" dongsheng@627: "literal> above)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1068 dongsheng@627: msgid "" dongsheng@627: "In addition, you can add a <envar role=\"rc-item-web\">baseurl</envar> item " dongsheng@627: "to the <literal role=\"rc-web\">web</literal> section of your <filename role=" dongsheng@627: "\"special\"> /.hgrc</filename>. The <literal role=\"hg-ext\">bugzilla</" dongsheng@627: "literal> hook will make this available when expanding a template, as the base " dongsheng@627: "string to use when constructing a URL that will let users browse from a " dongsheng@627: "Bugzilla comment to view a changeset. Example:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1080 dongsheng@627: msgid "" dongsheng@627: "Here is an example set of <literal role=\"hg-ext\">bugzilla</literal> hook " dongsheng@627: "config information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1097 dongsheng@627: msgid "" dongsheng@627: "The most common problems with configuring the <literal role=\"hg-ext" dongsheng@627: "\">bugzilla</literal> hook relate to running Bugzilla's " dongsheng@627: "<filename>processmail</filename> script and mapping committer names to user " dongsheng@627: "names." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1103 dongsheng@627: msgid "" dongsheng@627: "Recall from section <xref linkend=\"sec.hook.bugzilla.config\"/> above that " dongsheng@627: "the user that runs the Mercurial process on the server is also the one that " dongsheng@627: "will run the <filename>processmail</filename> script. The " dongsheng@627: "<filename>processmail</filename> script sometimes causes Bugzilla to write to " dongsheng@627: "files in its configuration directory, and Bugzilla's configuration files are " dongsheng@627: "usually owned by the user that your web server runs under." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1114 dongsheng@627: msgid "" dongsheng@627: "You can cause <filename>processmail</filename> to be run with the suitable " dongsheng@627: "user's identity using the <command>sudo</command> command. Here is an " dongsheng@627: "example entry for a <filename>sudoers</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1122 dongsheng@627: msgid "" dongsheng@627: "This allows the <literal>hg_user</literal> user to run a " dongsheng@627: "<filename>processmail-wrapper</filename> program under the identity of " dongsheng@627: "<literal>httpd_user</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1127 dongsheng@627: msgid "" dongsheng@627: "This indirection through a wrapper script is necessary, because " dongsheng@627: "<filename>processmail</filename> expects to be run with its current directory " dongsheng@627: "set to wherever you installed Bugzilla; you can't specify that kind of " dongsheng@627: "constraint in a <filename>sudoers</filename> file. The contents of the " dongsheng@627: "wrapper script are simple:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1136 dongsheng@627: msgid "" dongsheng@627: "It doesn't seem to matter what email address you pass to " dongsheng@627: "<filename>processmail</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1140 dongsheng@627: msgid "" dongsheng@627: "If your <literal role=\"rc-usermap\">usermap</literal> is not set up " dongsheng@627: "correctly, users will see an error message from the <literal role=\"hg-ext" dongsheng@627: "\">bugzilla</literal> hook when they push changes to the server. The error " dongsheng@627: "message will look like this:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1148 dongsheng@627: msgid "" dongsheng@627: "What this means is that the committer's address, <literal>john.q." dongsheng@627: "public@example.com</literal>, is not a valid Bugzilla user name, nor does it " dongsheng@627: "have an entry in your <literal role=\"rc-usermap\">usermap</literal> that " dongsheng@627: "maps it to a valid Bugzilla user name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1158 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hg-ext\">notify</literal>&emdash;send email notifications" dongsheng@635: msgstr "<literal role=\"hg-ext\">notify</literal>&emdash;邮件通知" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1161 dongsheng@627: msgid "" dongsheng@627: "Although Mercurial's built-in web server provides RSS feeds of changes in " dongsheng@627: "every repository, many people prefer to receive change notifications via " dongsheng@627: "email. The <literal role=\"hg-ext\">notify</literal> hook lets you send out " dongsheng@627: "notifications to a set of email addresses whenever changesets arrive that " dongsheng@627: "those subscribers are interested in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1169 dongsheng@627: msgid "" dongsheng@627: "As with the <literal role=\"hg-ext\">bugzilla</literal> hook, the <literal " dongsheng@627: "role=\"hg-ext\">notify</literal> hook is template-driven, so you can " dongsheng@627: "customise the contents of the notification messages that it sends." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1175 dongsheng@627: msgid "" dongsheng@627: "By default, the <literal role=\"hg-ext\">notify</literal> hook includes a " dongsheng@627: "diff of every changeset that it sends out; you can limit the size of the " dongsheng@627: "diff, or turn this feature off entirely. It is useful for letting " dongsheng@627: "subscribers review changes immediately, rather than clicking to follow a URL." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:1183 dongsheng@627: msgid "Configuring the <literal role=\"hg-ext\">notify</literal> hook" dongsheng@635: msgstr "配置 <literal role=\"hg-ext\">notify</literal> 钩子" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1186 dongsheng@627: msgid "" dongsheng@627: "You can set up the <literal role=\"hg-ext\">notify</literal> hook to send one " dongsheng@627: "email message per incoming changeset, or one per incoming group of changesets " dongsheng@627: "(all those that arrived in a single pull or push)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1197 dongsheng@627: msgid "" dongsheng@627: "Configuration information for this hook lives in the <literal role=\"rc-notify" dongsheng@627: "\">notify</literal> section of a <filename role=\"special\"> /.hgrc</filename>" dongsheng@627: "\\ file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1202 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">test</envar>: By default, this hook does not " dongsheng@627: "send out email at all; instead, it prints the message that it " dongsheng@627: "<emphasis>would</emphasis> send. Set this item to <literal>false</literal> " dongsheng@627: "to allow email to be sent. The reason that sending of email is turned off by " dongsheng@627: "default is that it takes several tries to configure this extension exactly as " dongsheng@627: "you would like, and it would be bad form to spam subscribers with a number of " dongsheng@627: "<quote>broken</quote> notifications while you debug your configuration." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1214 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">config</envar>: The path to a configuration " dongsheng@627: "file that contains subscription information. This is kept separate from the " dongsheng@627: "main <filename role=\"special\"> /.hgrc</filename>\\ so that you can maintain " dongsheng@627: "it in a repository of its own. People can then clone that repository, update " dongsheng@627: "their subscriptions, and push the changes back to your server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1223 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">strip</envar>: The number of leading path " dongsheng@627: "separator characters to strip from a repository's path, when deciding whether " dongsheng@627: "a repository has subscribers. For example, if the repositories on your " dongsheng@627: "server live in <filename class=\"directory\">/home/hg/repos</filename>, and " dongsheng@627: "<literal role=\"hg-ext\">notify</literal> is considering a repository named " dongsheng@627: "<filename class=\"directory\">/home/hg/repos/shared/test</filename>, setting " dongsheng@627: "<envar role=\"rc-item-notify\">strip</envar> to <literal>4</literal> will " dongsheng@627: "cause <literal role=\"hg-ext\">notify</literal> to trim the path it considers " dongsheng@627: "down to <filename class=\"directory\">shared/test</filename>, and it will " dongsheng@627: "match subscribers against that." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1240 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">template</envar>: The template text to use " dongsheng@627: "when sending messages. This specifies both the contents of the message " dongsheng@627: "header and its body." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1246 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">maxdiff</envar>: The maximum number of lines " dongsheng@627: "of diff data to append to the end of a message. If a diff is longer than " dongsheng@627: "this, it is truncated. By default, this is set to 300. Set this to " dongsheng@627: "<literal>0</literal> to omit diffs from notification emails." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1255 dongsheng@627: msgid "" dongsheng@627: "<envar role=\"rc-item-notify\">sources</envar>: A list of sources of " dongsheng@627: "changesets to consider. This lets you limit <literal role=\"hg-ext\">notify</" dongsheng@627: "literal> to only sending out email about changes that remote users pushed " dongsheng@627: "into this repository via a server, for example. See section <xref linkend=" dongsheng@627: "\"sec.hook.sources\"/> for the sources you can specify here." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1267 dongsheng@627: msgid "" dongsheng@627: "If you set the <envar role=\"rc-item-web\">baseurl</envar> item in the " dongsheng@627: "<literal role=\"rc-web\">web</literal> section, you can use it in a template; " dongsheng@627: "it will be available as <literal>webroot</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1273 dongsheng@627: msgid "" dongsheng@627: "Here is an example set of <literal role=\"hg-ext\">notify</literal> " dongsheng@627: "configuration information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1289 dongsheng@627: msgid "This will produce a message that looks like the following:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1310 dongsheng@627: msgid "" dongsheng@627: "Do not forget that by default, the <literal role=\"hg-ext\">notify</literal> " dongsheng@627: "extension <emphasis>will not send any mail</emphasis> until you explicitly " dongsheng@627: "configure it to do so, by setting <envar role=\"rc-item-notify\">test</envar> " dongsheng@627: "to <literal>false</literal>. Until you do that, it simply prints the message " dongsheng@627: "it <emphasis>would</emphasis> send." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:1322 dongsheng@627: msgid "Information for writers of hooks" dongsheng@635: msgstr "编写钩子的信息" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1325 dongsheng@627: msgid "In-process hook execution" dongsheng@635: msgstr "进程内钩子的执行" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1327 dongsheng@627: msgid "An in-process hook is called with arguments of the following form:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1333 dongsheng@627: msgid "" dongsheng@627: "The <literal>ui</literal> parameter is a <literal role=\"py-mod-mercurial.ui" dongsheng@627: "\">ui</literal> object. The <literal>repo</literal> parameter is a <literal " dongsheng@627: "role=\"py-mod-mercurial.localrepo\">localrepository</literal> object. The " dongsheng@627: "names and values of the <literal>**kwargs</literal> parameters depend on the " dongsheng@627: "hook being invoked, with the following common features:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1342 dongsheng@627: msgid "" dongsheng@627: "If a parameter is named <literal>node</literal> or <literal>parentN</" dongsheng@627: "literal>, it will contain a hexadecimal changeset ID. The empty string is " dongsheng@627: "used to represent <quote>null changeset ID</quote> instead of a string of " dongsheng@627: "zeroes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1349 dongsheng@627: msgid "" dongsheng@627: "If a parameter is named <literal>url</literal>, it will contain the URL of a " dongsheng@627: "remote repository, if that can be determined." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1354 dongsheng@627: msgid "" dongsheng@627: "Boolean-valued parameters are represented as Python <literal>bool</literal> " dongsheng@627: "objects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1359 dongsheng@627: msgid "" dongsheng@627: "An in-process hook is called without a change to the process's working " dongsheng@627: "directory (unlike external hooks, which are run in the root of the " dongsheng@627: "repository). It must not change the process's working directory, or it will " dongsheng@627: "cause any calls it makes into the Mercurial API to fail." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1366 dongsheng@627: msgid "" dongsheng@627: "If a hook returns a boolean <quote>false</quote> value, it is considered to " dongsheng@627: "have succeeded. If it returns a boolean <quote>true</quote> value or raises " dongsheng@627: "an exception, it is considered to have failed. A useful way to think of the " dongsheng@627: "calling convention is <quote>tell me if you fail</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1373 dongsheng@627: msgid "" dongsheng@627: "Note that changeset IDs are passed into Python hooks as hexadecimal strings, " dongsheng@627: "not the binary hashes that Mercurial's APIs normally use. To convert a hash " dongsheng@627: "from hex to binary, use the \\pymodfunc{mercurial.node}{bin} function." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1381 dongsheng@627: msgid "External hook execution" dongsheng@635: msgstr "外部钩子的执行" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1383 dongsheng@627: msgid "" dongsheng@627: "An external hook is passed to the shell of the user running Mercurial. " dongsheng@627: "Features of that shell, such as variable substitution and command " dongsheng@627: "redirection, are available. The hook is run in the root directory of the " dongsheng@627: "repository (unlike in-process hooks, which are run in the same directory that " dongsheng@627: "Mercurial was run in)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1391 dongsheng@627: msgid "" dongsheng@627: "Hook parameters are passed to the hook as environment variables. Each " dongsheng@627: "environment variable's name is converted in upper case and prefixed with the " dongsheng@627: "string <quote><literal>HG_</literal></quote>. For example, if the name of a " dongsheng@627: "parameter is <quote><literal>node</literal></quote>, the name of the " dongsheng@627: "environment variable representing that parameter will be " dongsheng@627: "<quote><literal>HG_NODE</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1400 dongsheng@627: msgid "" dongsheng@627: "A boolean parameter is represented as the string <quote><literal>1</literal></" dongsheng@627: "quote> for <quote>true</quote>, <quote><literal>0</literal></quote> for " dongsheng@627: "<quote>false</quote>. If an environment variable is named <envar>HG_NODE</" dongsheng@627: "envar>, <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it contains a " dongsheng@627: "changeset ID represented as a hexadecimal string. The empty string is used " dongsheng@627: "to represent <quote>null changeset ID</quote> instead of a string of zeroes. " dongsheng@627: "If an environment variable is named <envar>HG_URL</envar>, it will contain " dongsheng@627: "the URL of a remote repository, if that can be determined." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1412 dongsheng@627: msgid "" dongsheng@627: "If a hook exits with a status of zero, it is considered to have succeeded. " dongsheng@627: "If it exits with a non-zero status, it is considered to have failed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1419 dongsheng@627: msgid "Finding out where changesets come from" dongsheng@635: msgstr "检查修改集来自何处" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1421 dongsheng@627: msgid "" dongsheng@627: "A hook that involves the transfer of changesets between a local repository " dongsheng@627: "and another may be able to find out information about the <quote>far side</" dongsheng@627: "quote>. Mercurial knows <emphasis>how</emphasis> changes are being " dongsheng@627: "transferred, and in many cases <emphasis>where</emphasis> they are being " dongsheng@627: "transferred to or from." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:1430 dongsheng@627: msgid "Sources of changesets" dongsheng@635: msgstr "修改集的来源" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1432 dongsheng@627: msgid "" dongsheng@627: "Mercurial will tell a hook what means are, or were, used to transfer " dongsheng@627: "changesets between repositories. This is provided by Mercurial in a Python " dongsheng@627: "parameter named <literal>source</literal>, or an environment variable named " dongsheng@627: "<envar>HG_SOURCE</envar>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1440 dongsheng@627: msgid "" dongsheng@627: "<literal>serve</literal>: Changesets are transferred to or from a remote " dongsheng@627: "repository over http or ssh." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1445 dongsheng@627: msgid "" dongsheng@627: "<literal>pull</literal>: Changesets are being transferred via a pull from one " dongsheng@627: "repository into another." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1450 dongsheng@627: msgid "" dongsheng@627: "<literal>push</literal>: Changesets are being transferred via a push from one " dongsheng@627: "repository into another." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1455 dongsheng@627: msgid "" dongsheng@627: "<literal>bundle</literal>: Changesets are being transferred to or from a " dongsheng@627: "bundle." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><title> dongsheng@627: #: ../en/ch10-hook.xml:1462 dongsheng@627: msgid "Where changes are going&emdash;remote repository URLs" dongsheng@635: msgstr "修改集要到哪里&emdash;远程版本库的地址" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1465 dongsheng@627: msgid "" dongsheng@627: "When possible, Mercurial will tell a hook the location of the <quote>far " dongsheng@627: "side</quote> of an activity that transfers changeset data between " dongsheng@627: "repositories. This is provided by Mercurial in a Python parameter named " dongsheng@627: "<literal>url</literal>, or an environment variable named <envar>HG_URL</" dongsheng@627: "envar>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><para> dongsheng@627: #: ../en/ch10-hook.xml:1473 dongsheng@627: msgid "" dongsheng@627: "This information is not always known. If a hook is invoked in a repository " dongsheng@627: "that is being served via http or ssh, Mercurial cannot tell where the remote " dongsheng@627: "repository is, but it may know where the client is connecting from. In such " dongsheng@627: "cases, the URL will take one of the following forms:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1480 dongsheng@627: msgid "" dongsheng@627: "<literal>remote:ssh:1.2.3.4</literal>&emdash;remote ssh client, at the IP " dongsheng@627: "address <literal>1.2.3.4</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1485 dongsheng@627: msgid "" dongsheng@627: "<literal>remote:http:1.2.3.4</literal>&emdash;remote http client, at the IP " dongsheng@627: "address <literal>1.2.3.4</literal>. If the client is using SSL, this will be " dongsheng@627: "of the form <literal>remote:https:1.2.3.4</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1492 dongsheng@627: msgid "Empty&emdash;no information could be discovered about the remote client." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch10-hook.xml:1501 dongsheng@627: msgid "Hook reference" dongsheng@635: msgstr "钩子参考" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1504 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">changegroup</literal>&emdash;after remote changesets " dongsheng@627: "added" dongsheng@635: msgstr "<literal role=\"hook\">changegroup</literal>&emdash;增加远程修改集之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1507 dongsheng@627: msgid "" dongsheng@627: "This hook is run after a group of pre-existing changesets has been added to " dongsheng@627: "the repository, for example via a <command role=\"hg-cmd\">hg pull</command> " dongsheng@627: "or <command role=\"hg-cmd\">hg unbundle</command>. This hook is run once per " dongsheng@627: "operation that added one or more changesets. This is in contrast to the " dongsheng@627: "<literal role=\"hook\">incoming</literal> hook, which is run once per " dongsheng@627: "changeset, regardless of whether the changesets arrive in a group." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1517 dongsheng@627: msgid "" dongsheng@627: "Some possible uses for this hook include kicking off an automated build or " dongsheng@627: "test of the added changesets, updating a bug database, or notifying " dongsheng@627: "subscribers that a repository contains new changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1523 ../en/ch10-hook.xml:1564 ../en/ch10-hook.xml:1607 dongsheng@627: #: ../en/ch10-hook.xml:1649 ../en/ch10-hook.xml:1704 ../en/ch10-hook.xml:1744 dongsheng@627: #: ../en/ch10-hook.xml:1780 ../en/ch10-hook.xml:1815 ../en/ch10-hook.xml:1877 dongsheng@627: #: ../en/ch10-hook.xml:1935 ../en/ch10-hook.xml:1969 ../en/ch10-hook.xml:1997 dongsheng@627: msgid "Parameters to this hook:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1526 ../en/ch10-hook.xml:1880 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The changeset ID of the first " dongsheng@627: "changeset in the group that was added. All changesets between this and " dongsheng@627: "\\index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were " dongsheng@627: "added by a single <command role=\"hg-cmd\">hg pull</command>, <command role=" dongsheng@627: "\"hg-cmd\">hg push</command> or <command role=\"hg-cmd\">hg unbundle</" dongsheng@627: "command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1536 ../en/ch10-hook.xml:1614 ../en/ch10-hook.xml:1707 dongsheng@627: #: ../en/ch10-hook.xml:1890 dongsheng@627: msgid "" dongsheng@627: "<literal>source</literal>: A string. The source of these changes. See " dongsheng@627: "section <xref linkend=\"sec.hook.sources\"/> for details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1541 ../en/ch10-hook.xml:1619 ../en/ch10-hook.xml:1670 dongsheng@627: #: ../en/ch10-hook.xml:1712 ../en/ch10-hook.xml:1794 ../en/ch10-hook.xml:1895 dongsheng@627: msgid "" dongsheng@627: "<literal>url</literal>: A URL. The location of the remote repository, if " dongsheng@627: "known. See section <xref linkend=\"sec.hook.url\"/> for more information." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1548 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">incoming</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.incoming\"/>), <literal role=\"hook\">prechangegroup</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.prechangegroup\"/>), <literal role=\"hook" dongsheng@627: "\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook." dongsheng@627: "pretxnchangegroup\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1558 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">commit</literal>&emdash;after a new changeset is " dongsheng@627: "created" dongsheng@635: msgstr "<literal role=\"hook\">commit</literal>&emdash;创建新修改集之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1561 dongsheng@627: msgid "This hook is run after a new changeset has been created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1567 ../en/ch10-hook.xml:1938 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The changeset ID of the newly " dongsheng@627: "committed changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1571 ../en/ch10-hook.xml:1942 dongsheng@627: msgid "" dongsheng@627: "<literal>parent1</literal>: A changeset ID. The changeset ID of the first " dongsheng@627: "parent of the newly committed changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1576 ../en/ch10-hook.xml:1947 dongsheng@627: msgid "" dongsheng@627: "<literal>parent2</literal>: A changeset ID. The changeset ID of the second " dongsheng@627: "parent of the newly committed changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1582 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">precommit</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.precommit\"/>), <literal role=\"hook\">pretxncommit</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.pretxncommit\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1590 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">incoming</literal>&emdash;after one remote changeset " dongsheng@627: "is added" dongsheng@635: msgstr "<literal role=\"hook\">incoming</literal>&emdash;增加远程修改集之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1593 dongsheng@627: msgid "" dongsheng@627: "This hook is run after a pre-existing changeset has been added to the " dongsheng@627: "repository, for example via a <command role=\"hg-cmd\">hg push</command>. If " dongsheng@627: "a group of changesets was added in a single operation, this hook is called " dongsheng@627: "once for each added changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1600 dongsheng@627: msgid "" dongsheng@627: "You can use this hook for the same purposes as the <literal role=\"hook" dongsheng@627: "\">changegroup</literal> hook (section <xref linkend=\"sec.hook.changegroup\"/" dongsheng@627: ">); it's simply more convenient sometimes to run a hook once per group of " dongsheng@627: "changesets, while other times it's handier once per changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1610 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The ID of the newly added changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1626 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.changegroup\"/>) <literal role=\"hook\">prechangegroup</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.prechangegroup\"/>), <literal role=\"hook" dongsheng@627: "\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook." dongsheng@627: "pretxnchangegroup\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1636 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">outgoing</literal>&emdash;after changesets are " dongsheng@627: "propagated" dongsheng@635: msgstr "<literal role=\"hook\">outgoing</literal>&emdash;传播修改集之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1639 dongsheng@627: msgid "" dongsheng@627: "This hook is run after a group of changesets has been propagated out of this " dongsheng@627: "repository, for example by a <command role=\"hg-cmd\">hg push</command> or " dongsheng@627: "<command role=\"hg-cmd\">hg bundle</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1645 dongsheng@627: msgid "" dongsheng@627: "One possible use for this hook is to notify administrators that changes have " dongsheng@627: "been pulled." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1652 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The changeset ID of the first " dongsheng@627: "changeset of the group that was sent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1657 dongsheng@627: msgid "" dongsheng@627: "<literal>source</literal>: A string. The source of the of the operation (see " dongsheng@627: "section <xref linkend=\"sec.hook.sources\"/>). If a remote client pulled " dongsheng@627: "changes from this repository, <literal>source</literal> will be " dongsheng@627: "<literal>serve</literal>. If the client that obtained changes from this " dongsheng@627: "repository was local, <literal>source</literal> will be <literal>bundle</" dongsheng@627: "literal>, <literal>pull</literal>, or <literal>push</literal>, depending on " dongsheng@627: "the operation the client performed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1677 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">preoutgoing</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.preoutgoing\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1683 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">prechangegroup</literal>&emdash;before starting to add " dongsheng@627: "remote changesets" dongsheng@627: msgstr "" dongsheng@635: "<literal role=\"hook\">prechangegroup</literal>&emdash;增加远程修改集之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1687 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before Mercurial begins to add a group of " dongsheng@627: "changesets from another repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1691 dongsheng@627: msgid "" dongsheng@627: "This hook does not have any information about the changesets to be added, " dongsheng@627: "because it is run before transmission of those changesets is allowed to " dongsheng@627: "begin. If this hook fails, the changesets will not be transmitted." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1697 dongsheng@627: msgid "" dongsheng@627: "One use for this hook is to prevent external changes from being added to a " dongsheng@627: "repository. For example, you could use this to <quote>freeze</quote> a " dongsheng@627: "server-hosted branch temporarily or permanently so that users cannot push to " dongsheng@627: "it, while still allowing a local administrator to modify the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1719 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.changegroup\"/>), <literal role=\"hook\">incoming</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.incoming\"/>), , <literal role=\"hook" dongsheng@627: "\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook." dongsheng@627: "pretxnchangegroup\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1729 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">precommit</literal>&emdash;before starting to commit a " dongsheng@627: "changeset" dongsheng@635: msgstr "<literal role=\"hook\">precommit</literal>&emdash;提交修改集之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1732 dongsheng@627: msgid "" dongsheng@627: "This hook is run before Mercurial begins to commit a new changeset. It is run " dongsheng@627: "before Mercurial has any of the metadata for the commit, such as the files to " dongsheng@627: "be committed, the commit message, or the commit date." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1738 dongsheng@627: msgid "" dongsheng@627: "One use for this hook is to disable the ability to commit new changesets, " dongsheng@627: "while still allowing incoming changesets. Another is to run a build or test, " dongsheng@627: "and only allow the commit to begin if the build or test succeeds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1747 dongsheng@627: msgid "" dongsheng@627: "<literal>parent1</literal>: A changeset ID. The changeset ID of the first " dongsheng@627: "parent of the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1752 dongsheng@627: msgid "" dongsheng@627: "<literal>parent2</literal>: A changeset ID. The changeset ID of the second " dongsheng@627: "parent of the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1757 dongsheng@627: msgid "" dongsheng@627: "If the commit proceeds, the parents of the working directory will become the " dongsheng@627: "parents of the new changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1761 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">commit</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.commit\"/>), <literal role=\"hook\">pretxncommit</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.pretxncommit\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1769 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">preoutgoing</literal>&emdash;before starting to " dongsheng@627: "propagate changesets" dongsheng@635: msgstr "<literal role=\"hook\">preoutgoing</literal>&emdash;传播修改集之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1772 dongsheng@627: msgid "" dongsheng@627: "This hook is invoked before Mercurial knows the identities of the changesets " dongsheng@627: "to be transmitted." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1776 dongsheng@627: msgid "" dongsheng@627: "One use for this hook is to prevent changes from being transmitted to another " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1783 dongsheng@627: msgid "" dongsheng@627: "<literal>source</literal>: A string. The source of the operation that is " dongsheng@627: "attempting to obtain changes from this repository (see section <xref linkend=" dongsheng@627: "\"sec.hook.sources\"/>). See the documentation for the <literal>source</" dongsheng@627: "literal> parameter to the <literal role=\"hook\">outgoing</literal> hook, in " dongsheng@627: "section <xref linkend=\"sec.hook.outgoing\"/>, for possible values of this " dongsheng@627: "parameter." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1801 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">outgoing</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.outgoing\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1807 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretag</literal>&emdash;before tagging a changeset" dongsheng@635: msgstr "<literal role=\"hook\">pretag</literal>&emdash;创建标签之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1810 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before a tag is created. If the hook succeeds, " dongsheng@627: "creation of the tag proceeds. If the hook fails, the tag is not created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1818 dongsheng@627: msgid "" dongsheng@627: "<literal>local</literal>: A boolean. Whether the tag is local to this " dongsheng@627: "repository instance (i.e. stored in <filename role=\"special\">.hg/localtags</" dongsheng@627: "filename>) or managed by Mercurial (stored in <filename role=\"special\">." dongsheng@627: "hgtags</filename>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1825 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The ID of the changeset to be " dongsheng@627: "tagged." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1829 dongsheng@627: msgid "<literal>tag</literal>: A string. The name of the tag to be created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1834 dongsheng@627: msgid "" dongsheng@627: "If the tag to be created is revision-controlled, the <literal role=\"hook" dongsheng@627: "\">precommit</literal> and <literal role=\"hook\">pretxncommit</literal> " dongsheng@627: "hooks (sections <xref linkend=\"sec.hook.commit\"/> and <xref linkend=\"sec." dongsheng@627: "hook.pretxncommit\"/>) will also be run." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1841 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">tag</literal> (section <xref linkend=\"sec." dongsheng@627: "hook.tag\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1846 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretxnchangegroup</literal>&emdash;before completing " dongsheng@627: "addition of remote changesets" dongsheng@627: msgstr "" dongsheng@635: "<literal role=\"hook\">pretxnchangegroup</literal>&emdash;完成增加远程修改集之" dongsheng@635: "前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1850 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before a transaction&emdash;that manages the " dongsheng@627: "addition of a group of new changesets from outside the repository&emdash;" dongsheng@627: "completes. If the hook succeeds, the transaction completes, and all of the " dongsheng@627: "changesets become permanent within this repository. If the hook fails, the " dongsheng@627: "transaction is rolled back, and the data for the changesets is erased." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1859 dongsheng@627: msgid "" dongsheng@627: "This hook can access the metadata associated with the almost-added " dongsheng@627: "changesets, but it should not do anything permanent with this data. It must " dongsheng@627: "also not modify the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1865 dongsheng@627: msgid "" dongsheng@627: "While this hook is running, if other Mercurial processes access this " dongsheng@627: "repository, they will be able to see the almost-added changesets as if they " dongsheng@627: "are permanent. This may lead to race conditions if you do not take steps to " dongsheng@627: "avoid them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1872 dongsheng@627: msgid "" dongsheng@627: "This hook can be used to automatically vet a group of changesets. If the " dongsheng@627: "hook fails, all of the changesets are <quote>rejected</quote> when the " dongsheng@627: "transaction rolls back." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1902 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.changegroup\"/>), <literal role=\"hook\">incoming</literal> " dongsheng@627: "(section <xref linkend=\"sec.hook.incoming\"/>), <literal role=\"hook" dongsheng@627: "\">prechangegroup</literal> (section <xref linkend=\"sec.hook.prechangegroup" dongsheng@627: "\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1912 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">pretxncommit</literal>&emdash;before completing commit " dongsheng@627: "of new changeset" dongsheng@635: msgstr "<literal role=\"hook\">pretxncommit</literal>&emdash;完成提交之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1915 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before a transaction&emdash;that manages a new " dongsheng@627: "commit&emdash;completes. If the hook succeeds, the transaction completes and " dongsheng@627: "the changeset becomes permanent within this repository. If the hook fails, " dongsheng@627: "the transaction is rolled back, and the commit data is erased." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1923 dongsheng@627: msgid "" dongsheng@627: "This hook can access the metadata associated with the almost-new changeset, " dongsheng@627: "but it should not do anything permanent with this data. It must also not " dongsheng@627: "modify the working directory." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1929 dongsheng@627: msgid "" dongsheng@627: "While this hook is running, if other Mercurial processes access this " dongsheng@627: "repository, they will be able to see the almost-new changeset as if it is " dongsheng@627: "permanent. This may lead to race conditions if you do not take steps to " dongsheng@627: "avoid them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1953 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">precommit</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.precommit\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1959 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">preupdate</literal>&emdash;before updating or merging " dongsheng@627: "working directory" dongsheng@627: msgstr "" dongsheng@635: "<literal role=\"hook\">preupdate</literal>&emdash;更新或合并工作目录之前" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1962 dongsheng@627: msgid "" dongsheng@627: "This controlling hook is run before an update or merge of the working " dongsheng@627: "directory begins. It is run only if Mercurial's normal pre-update checks " dongsheng@627: "determine that the update or merge can proceed. If the hook succeeds, the " dongsheng@627: "update or merge may proceed; if it fails, the update or merge does not start." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1972 dongsheng@627: msgid "" dongsheng@627: "<literal>parent1</literal>: A changeset ID. The ID of the parent that the " dongsheng@627: "working directory is to be updated to. If the working directory is being " dongsheng@627: "merged, it will not change this parent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:1978 dongsheng@627: msgid "" dongsheng@627: "<literal>parent2</literal>: A changeset ID. Only set if the working " dongsheng@627: "directory is being merged. The ID of the revision that the working directory " dongsheng@627: "is being merged with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1985 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">update</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.update\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:1991 dongsheng@627: msgid "<literal role=\"hook\">tag</literal>&emdash;after tagging a changeset" dongsheng@635: msgstr "<literal role=\"hook\">tag</literal>&emdash;创建标签之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:1994 dongsheng@627: msgid "This hook is run after a tag has been created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2000 dongsheng@627: msgid "" dongsheng@627: "<literal>local</literal>: A boolean. Whether the new tag is local to this " dongsheng@627: "repository instance (i.e. stored in <filename role=\"special\">.hg/" dongsheng@627: "localtags</filename>) or managed by Mercurial (stored in <filename role=" dongsheng@627: "\"special\">.hgtags</filename>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2008 dongsheng@627: msgid "" dongsheng@627: "<literal>node</literal>: A changeset ID. The ID of the changeset that was " dongsheng@627: "tagged." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2012 dongsheng@627: msgid "<literal>tag</literal>: A string. The name of the tag that was created." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:2017 dongsheng@627: msgid "" dongsheng@627: "If the created tag is revision-controlled, the <literal role=\"hook\">commit</" dongsheng@627: "literal> hook (section <xref linkend=\"sec.hook.commit\"/>) is run before " dongsheng@627: "this hook." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:2022 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">pretag</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.pretag\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch10-hook.xml:2028 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"hook\">update</literal>&emdash;after updating or merging " dongsheng@627: "working directory" dongsheng@635: msgstr "<literal role=\"hook\">update</literal>&emdash;更新或合并工作目录之后" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:2031 dongsheng@627: msgid "" dongsheng@627: "This hook is run after an update or merge of the working directory " dongsheng@627: "completes. Since a merge can fail (if the external <command>hgmerge</" dongsheng@627: "command> command fails to resolve conflicts in a file), this hook " dongsheng@627: "communicates whether the update or merge completed cleanly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2039 dongsheng@627: msgid "" dongsheng@627: "<literal>error</literal>: A boolean. Indicates whether the update or merge " dongsheng@627: "completed successfully." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2044 dongsheng@627: msgid "" dongsheng@627: "<literal>parent1</literal>: A changeset ID. The ID of the parent that the " dongsheng@627: "working directory was updated to. If the working directory was merged, it " dongsheng@627: "will not have changed this parent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch10-hook.xml:2050 dongsheng@627: msgid "" dongsheng@627: "<literal>parent2</literal>: A changeset ID. Only set if the working " dongsheng@627: "directory was merged. The ID of the revision that the working directory was " dongsheng@627: "merged with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch10-hook.xml:2056 dongsheng@627: msgid "" dongsheng@627: "See also: <literal role=\"hook\">preupdate</literal> (section <xref linkend=" dongsheng@627: "\"sec.hook.preupdate\"/>)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch11-template.xml:5 dongsheng@627: msgid "Customising the output of Mercurial" dongsheng@627: msgstr "定制 Mercurial 的输出" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch11-template.xml:7 dongsheng@627: msgid "" dongsheng@627: "Mercurial provides a powerful mechanism to let you control how it displays " dongsheng@627: "information. The mechanism is based on templates. You can use templates to " dongsheng@627: "generate specific output for a single command, or to customise the entire " dongsheng@627: "appearance of the built-in web interface." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:14 dongsheng@627: msgid "Using precanned output styles" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:16 dongsheng@627: msgid "" dongsheng@627: "Packaged with Mercurial are some output styles that you can use immediately. " dongsheng@627: "A style is simply a precanned template that someone wrote and installed " dongsheng@627: "somewhere that Mercurial can find." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:21 dongsheng@627: msgid "" dongsheng@627: "Before we take a look at Mercurial's bundled styles, let's review its normal " dongsheng@627: "output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:26 dongsheng@627: msgid "" dongsheng@627: "This is somewhat informative, but it takes up a lot of space&emdash;five " dongsheng@627: "lines of output per changeset. The <literal>compact</literal> style reduces " dongsheng@627: "this to three lines, presented in a sparse manner." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:33 dongsheng@627: msgid "" dongsheng@627: "The <literal>changelog</literal> style hints at the expressive power of " dongsheng@627: "Mercurial's templating engine. This style attempts to follow the GNU " dongsheng@627: "Project's changelog guidelines<citation>web:changelog</citation>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:40 dongsheng@627: msgid "" dongsheng@627: "You will not be shocked to learn that Mercurial's default output style is " dongsheng@627: "named <literal>default</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:44 dongsheng@627: msgid "Setting a default style" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:46 dongsheng@627: msgid "" dongsheng@627: "You can modify the output style that Mercurial will use for every command by " dongsheng@627: "editing your <filename role=\"special\"> /.hgrc</filename>\\ file, naming the " dongsheng@627: "style you would prefer to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:53 dongsheng@627: msgid "" dongsheng@627: "If you write a style of your own, you can use it by either providing the path " dongsheng@627: "to your style file, or copying your style file into a location where " dongsheng@627: "Mercurial can find it (typically the <literal>templates</literal> " dongsheng@627: "subdirectory of your Mercurial install directory)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:62 dongsheng@627: msgid "Commands that support styles and templates" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:64 dongsheng@627: msgid "" dongsheng@627: "All of Mercurial's <quote><literal>log</literal>-like</quote> commands let " dongsheng@627: "you use styles and templates: <command role=\"hg-cmd\">hg incoming</command>, " dongsheng@627: "<command role=\"hg-cmd\">hg log</command>, <command role=\"hg-cmd\">hg " dongsheng@627: "outgoing</command>, and <command role=\"hg-cmd\">hg tip</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:71 dongsheng@627: msgid "" dongsheng@627: "As I write this manual, these are so far the only commands that support " dongsheng@627: "styles and templates. Since these are the most important commands that need " dongsheng@627: "customisable output, there has been little pressure from the Mercurial user " dongsheng@627: "community to add style and template support to other commands." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:79 dongsheng@627: msgid "The basics of templating" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:81 dongsheng@627: msgid "" dongsheng@627: "At its simplest, a Mercurial template is a piece of text. Some of the text " dongsheng@627: "never changes, while other parts are <emphasis>expanded</emphasis>, or " dongsheng@627: "replaced with new text, when necessary." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:86 dongsheng@627: msgid "" dongsheng@627: "Before we continue, let's look again at a simple example of Mercurial's " dongsheng@627: "normal output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:91 dongsheng@627: msgid "" dongsheng@627: "Now, let's run the same command, but using a template to change its output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:96 dongsheng@627: msgid "" dongsheng@627: "The example above illustrates the simplest possible template; it's just a " dongsheng@627: "piece of static text, printed once for each changeset. The <option role=\"hg-" dongsheng@627: "opt-log\">--template</option> option to the <command role=\"hg-cmd\">hg log</" dongsheng@627: "command> command tells Mercurial to use the given text as the template when " dongsheng@627: "printing each changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:104 dongsheng@627: msgid "" dongsheng@627: "Notice that the template string above ends with the text <quote><literal>\\n</" dongsheng@627: "literal></quote>. This is an <emphasis>escape sequence</emphasis>, telling " dongsheng@627: "Mercurial to print a newline at the end of each template item. If you omit " dongsheng@627: "this newline, Mercurial will run each piece of output together. See section " dongsheng@627: "<xref linkend=\"sec.template.escape\"/> for more details of escape sequences." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:112 dongsheng@627: msgid "" dongsheng@627: "A template that prints a fixed string of text all the time isn't very useful; " dongsheng@627: "let's try something a bit more complex." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:118 dongsheng@627: msgid "" dongsheng@627: "As you can see, the string <quote><literal>{desc}</literal></quote> in the " dongsheng@627: "template has been replaced in the output with the description of each " dongsheng@627: "changeset. Every time Mercurial finds text enclosed in curly braces " dongsheng@627: "(<quote><literal>{</literal></quote> and <quote><literal>}</literal></" dongsheng@627: "quote>), it will try to replace the braces and text with the expansion of " dongsheng@627: "whatever is inside. To print a literal curly brace, you must escape it, as " dongsheng@627: "described in section <xref linkend=\"sec.template.escape\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:131 dongsheng@627: msgid "Common template keywords" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:133 dongsheng@627: msgid "" dongsheng@627: "You can start writing simple templates immediately using the keywords below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:137 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">author</literal>: String. The unmodified " dongsheng@627: "author of the changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:141 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">branches</literal>: String. The name of " dongsheng@627: "the branch on which the changeset was committed. Will be empty if the branch " dongsheng@627: "name was <literal>default</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:147 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">date</literal>: Date information. The " dongsheng@627: "date when the changeset was committed. This is <emphasis>not</emphasis> " dongsheng@627: "human-readable; you must pass it through a filter that will render it " dongsheng@627: "appropriately. See section <xref linkend=\"sec.template.filter\"/> for more " dongsheng@627: "information on filters. The date is expressed as a pair of numbers. The " dongsheng@627: "first number is a Unix UTC timestamp (seconds since January 1, 1970); the " dongsheng@627: "second is the offset of the committer's timezone from UTC, in seconds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:158 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">desc</literal>: String. The text of the " dongsheng@627: "changeset description." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:161 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">files</literal>: List of strings. All " dongsheng@627: "files modified, added, or removed by this changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:166 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">file_adds</literal>: List of strings. " dongsheng@627: "Files added by this changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:170 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">file_dels</literal>: List of strings. " dongsheng@627: "Files removed by this changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:174 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">node</literal>: String. The changeset " dongsheng@627: "identification hash, as a 40-character hexadecimal string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:178 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">parents</literal>: List of strings. The " dongsheng@627: "parents of the changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:182 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">rev</literal>: Integer. The repository-" dongsheng@627: "local changeset revision number." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:186 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-keyword\">tags</literal>: List of strings. Any tags " dongsheng@627: "associated with the changeset." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:191 dongsheng@627: msgid "" dongsheng@627: "A few simple experiments will show us what to expect when we use these " dongsheng@627: "keywords; you can see the results below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:196 dongsheng@627: msgid "" dongsheng@627: "As we noted above, the date keyword does not produce human-readable output, " dongsheng@627: "so we must treat it specially. This involves using a <emphasis>filter</" dongsheng@627: "emphasis>, about which more in section <xref linkend=\"sec.template.filter\"/" dongsheng@627: ">." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:206 dongsheng@627: msgid "Escape sequences" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:208 dongsheng@627: msgid "" dongsheng@627: "Mercurial's templating engine recognises the most commonly used escape " dongsheng@627: "sequences in strings. When it sees a backslash (<quote><literal>\\</" dongsheng@627: "literal></quote>) character, it looks at the following character and " dongsheng@627: "substitutes the two characters with a single replacement, as described below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:215 dongsheng@627: msgid "" dongsheng@627: "<literal>\\textbackslash\\textbackslash</literal>: Backslash, <quote><literal>" dongsheng@627: "\\</literal></quote>, ASCII 134." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:219 dongsheng@627: msgid "<literal>\\textbackslash n</literal>: Newline, ASCII 12." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:222 dongsheng@627: msgid "<literal>\\textbackslash r</literal>: Carriage return, ASCII 15." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:225 dongsheng@627: msgid "<literal>\\textbackslash t</literal>: Tab, ASCII 11." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:228 dongsheng@627: msgid "<literal>\\textbackslash v</literal>: Vertical tab, ASCII 13." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:231 dongsheng@627: msgid "" dongsheng@627: "<literal>\\textbackslash {</literal>: Open curly brace, <quote><literal>{</" dongsheng@627: "literal></quote>, ASCII 173." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:235 dongsheng@627: msgid "" dongsheng@627: "<literal>\\textbackslash }</literal>: Close curly brace, <quote><literal>}</" dongsheng@627: "literal></quote>, ASCII 175." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:240 dongsheng@627: msgid "" dongsheng@627: "As indicated above, if you want the expansion of a template to contain a " dongsheng@627: "literal <quote><literal>\\</literal></quote>, <quote><literal>{</literal></" dongsheng@627: "quote>, or <quote><literal>{</literal></quote> character, you must escape it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:248 dongsheng@627: msgid "Filtering keywords to change their results" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:250 dongsheng@627: msgid "" dongsheng@627: "Some of the results of template expansion are not immediately easy to use. " dongsheng@627: "Mercurial lets you specify an optional chain of <emphasis>filters</emphasis> " dongsheng@627: "to modify the result of expanding a keyword. You have already seen a common " dongsheng@627: "filter, <literal role=\"template-kw-filt-date\">isodate</literal>, in action " dongsheng@627: "above, to make a date readable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:257 dongsheng@627: msgid "" dongsheng@627: "Below is a list of the most commonly used filters that Mercurial supports. " dongsheng@627: "While some filters can be applied to any text, others can only be used in " dongsheng@627: "specific circumstances. The name of each filter is followed first by an " dongsheng@627: "indication of where it can be used, then a description of its effect." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:264 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">addbreaks</literal>: Any text. Add an XHTML " dongsheng@627: "<quote><literal><br/></literal></quote> tag before the end of every " dongsheng@627: "line except the last. For example, <quote><literal>foo\\nbar</literal></" dongsheng@627: "quote> becomes <quote><literal>foo<br/>\\nbar</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:271 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">age</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render the age of the date, " dongsheng@627: "relative to the current time. Yields a string like <quote><literal>10 " dongsheng@627: "minutes</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:278 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">basename</literal>: Any text, but most " dongsheng@627: "useful for the <literal role=\"template-keyword\">files</literal> keyword and " dongsheng@627: "its relatives. Treat the text as a path, and return the basename. For " dongsheng@627: "example, <quote><literal>foo/bar/baz</literal></quote> becomes " dongsheng@627: "<quote><literal>baz</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:287 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">date</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render a date in a similar " dongsheng@627: "format to the Unix <literal role=\"template-keyword\">date</literal> command, " dongsheng@627: "but with timezone included. Yields a string like <quote><literal>Mon Sep 04 " dongsheng@627: "15:13:13 2006 -0700</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:295 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-author\">domain</literal>: Any text, but " dongsheng@627: "most useful for the <literal role=\"template-keyword\">author</literal> " dongsheng@627: "keyword. Finds the first string that looks like an email address, and " dongsheng@627: "extract just the domain component. For example, <quote><literal>Bryan " dongsheng@627: "O'Sullivan <bos@serpentine.com></literal></quote> becomes " dongsheng@627: "<quote><literal>serpentine.com</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:305 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-author\">email</literal>: Any text, but most " dongsheng@627: "useful for the <literal role=\"template-keyword\">author</literal> keyword. " dongsheng@627: "Extract the first string that looks like an email address. For example, " dongsheng@627: "<quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> " dongsheng@627: "becomes <quote><literal>bos@serpentine.com</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:314 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">escape</literal>: Any text. Replace the " dongsheng@627: "special XML/XHTML characters <quote><literal>&</literal></quote>, " dongsheng@627: "<quote><literal><</literal></quote> and <quote><literal>></literal></" dongsheng@627: "quote> with XML entities." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:322 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">fill68</literal>: Any text. Wrap the text " dongsheng@627: "to fit in 68 columns. This is useful before you pass text through the " dongsheng@627: "<literal role=\"template-filter\">tabindent</literal> filter, and still want " dongsheng@627: "it to fit in an 80-column fixed-font window." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:330 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">fill76</literal>: Any text. Wrap the text " dongsheng@627: "to fit in 76 columns." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:334 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">firstline</literal>: Any text. Yield the " dongsheng@627: "first line of text, without any trailing newlines." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:339 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">hgdate</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render the date as a pair of " dongsheng@627: "readable numbers. Yields a string like <quote><literal>1157407993 25200</" dongsheng@627: "literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:346 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">isodate</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render the date as a text " dongsheng@627: "string in ISO 8601 format. Yields a string like <quote><literal>2006-09-04 " dongsheng@627: "15:13:13 -0700</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:353 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">obfuscate</literal>: Any text, but most " dongsheng@627: "useful for the <literal role=\"template-keyword\">author</literal> keyword. " dongsheng@627: "Yield the input text rendered as a sequence of XML entities. This helps to " dongsheng@627: "defeat some particularly stupid screen-scraping email harvesting spambots." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:361 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-author\">person</literal>: Any text, but " dongsheng@627: "most useful for the <literal role=\"template-keyword\">author</literal> " dongsheng@627: "keyword. Yield the text before an email address. For example, " dongsheng@627: "<quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> " dongsheng@627: "becomes <quote><literal>Bryan O'Sullivan</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:370 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">rfc822date</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render a date using the same " dongsheng@627: "format used in email headers. Yields a string like <quote><literal>Mon, 04 " dongsheng@627: "Sep 2006 15:13:13 -0700</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:377 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-node\">short</literal>: Changeset hash. " dongsheng@627: "Yield the short form of a changeset hash, i.e. a 12-character hexadecimal " dongsheng@627: "string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:382 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-date\">shortdate</literal>: <literal role=" dongsheng@627: "\"template-keyword\">date</literal> keyword. Render the year, month, and day " dongsheng@627: "of the date. Yields a string like <quote><literal>2006-09-04</literal></" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:388 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">strip</literal>: Any text. Strip all " dongsheng@627: "leading and trailing whitespace from the string." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:392 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">tabindent</literal>: Any text. Yield the " dongsheng@627: "text, with every line except the first starting with a tab character." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:397 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-filter\">urlescape</literal>: Any text. Escape all " dongsheng@627: "characters that are considered <quote>special</quote> by URL parsers. For " dongsheng@627: "example, <literal>foo bar</literal> becomes <literal>foo%20bar</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:404 dongsheng@627: msgid "" dongsheng@627: "<literal role=\"template-kw-filt-author\">user</literal>: Any text, but most " dongsheng@627: "useful for the <literal role=\"template-keyword\">author</literal> keyword. " dongsheng@627: "Return the <quote>user</quote> portion of an email address. For example, " dongsheng@627: "<quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> " dongsheng@627: "becomes <quote><literal>bos</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch11-template.xml:417 dongsheng@627: msgid "" dongsheng@627: "If you try to apply a filter to a piece of data that it cannot process, " dongsheng@627: "Mercurial will fail and print a Python exception. For example, trying to run " dongsheng@627: "the output of the <literal role=\"template-keyword\">desc</literal> keyword " dongsheng@627: "into the <literal role=\"template-kw-filt-date\">isodate</literal> filter is " dongsheng@627: "not a good idea." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:426 dongsheng@627: msgid "Combining filters" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:428 dongsheng@627: msgid "" dongsheng@627: "It is easy to combine filters to yield output in the form you would like. " dongsheng@627: "The following chain of filters tidies up a description, then makes sure that " dongsheng@627: "it fits cleanly into 68 columns, then indents it by a further 8 characters " dongsheng@627: "(at least on Unix-like systems, where a tab is conventionally 8 characters " dongsheng@627: "wide)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:437 dongsheng@627: msgid "" dongsheng@627: "Note the use of <quote><literal>\\t</literal></quote> (a tab character) in " dongsheng@627: "the template to force the first line to be indented; this is necessary since " dongsheng@627: "<literal role=\"template-keyword\">tabindent</literal> indents all lines " dongsheng@627: "<emphasis>except</emphasis> the first." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:443 dongsheng@627: msgid "" dongsheng@627: "Keep in mind that the order of filters in a chain is significant. The first " dongsheng@627: "filter is applied to the result of the keyword; the second to the result of " dongsheng@627: "the first filter; and so on. For example, using <literal>fill68|tabindent</" dongsheng@627: "literal> gives very different results from <literal>tabindent|fill68</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:454 dongsheng@627: msgid "From templates to styles" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:456 dongsheng@627: msgid "" dongsheng@627: "A command line template provides a quick and simple way to format some " dongsheng@627: "output. Templates can become verbose, though, and it's useful to be able to " dongsheng@627: "give a template a name. A style file is a template with a name, stored in a " dongsheng@627: "file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:461 dongsheng@627: msgid "" dongsheng@627: "More than that, using a style file unlocks the power of Mercurial's " dongsheng@627: "templating engine in ways that are not possible using the command line " dongsheng@627: "<option role=\"hg-opt-log\">--template</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:467 dongsheng@627: msgid "The simplest of style files" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:469 dongsheng@627: msgid "Our simple style file contains just one line:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:473 dongsheng@627: msgid "" dongsheng@627: "This tells Mercurial, <quote>if you're printing a changeset, use the text on " dongsheng@627: "the right as the template</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:479 dongsheng@627: msgid "Style file syntax" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:481 dongsheng@627: msgid "The syntax rules for a style file are simple." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:484 dongsheng@627: msgid "The file is processed one line at a time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:487 dongsheng@627: msgid "Leading and trailing white space are ignored." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:490 dongsheng@627: msgid "Empty lines are skipped." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:492 dongsheng@627: msgid "" dongsheng@627: "If a line starts with either of the characters <quote><literal>#</literal></" dongsheng@627: "quote> or <quote><literal>;</literal></quote>, the entire line is treated as " dongsheng@627: "a comment, and skipped as if empty." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:497 dongsheng@627: msgid "" dongsheng@627: "A line starts with a keyword. This must start with an alphabetic character " dongsheng@627: "or underscore, and can subsequently contain any alphanumeric character or " dongsheng@627: "underscore. (In regexp notation, a keyword must match <literal>[A-Za-z_][A-" dongsheng@627: "Za-z0-9_]*</literal>.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:503 dongsheng@627: msgid "" dongsheng@627: "The next element must be an <quote><literal>=</literal></quote> character, " dongsheng@627: "which can be preceded or followed by an arbitrary amount of white space." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:508 dongsheng@627: msgid "" dongsheng@627: "If the rest of the line starts and ends with matching quote characters " dongsheng@627: "(either single or double quote), it is treated as a template body." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:512 dongsheng@627: msgid "" dongsheng@627: "If the rest of the line <emphasis>does not</emphasis> start with a quote " dongsheng@627: "character, it is treated as the name of a file; the contents of this file " dongsheng@627: "will be read and used as a template body." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch11-template.xml:521 dongsheng@627: msgid "Style files by example" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch11-template.xml:523 dongsheng@627: msgid "" dongsheng@627: "To illustrate how to write a style file, we will construct a few by example. " dongsheng@627: "Rather than provide a complete style file and walk through it, we'll mirror " dongsheng@627: "the usual process of developing a style file by starting with something very " dongsheng@627: "simple, and walking through a series of successively more complete examples." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:530 dongsheng@627: msgid "Identifying mistakes in style files" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:532 dongsheng@627: msgid "" dongsheng@627: "If Mercurial encounters a problem in a style file you are working on, it " dongsheng@627: "prints a terse error message that, once you figure out what it means, is " dongsheng@627: "actually quite useful." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:538 dongsheng@627: msgid "" dongsheng@627: "Notice that <filename>broken.style</filename> attempts to define a " dongsheng@627: "<literal>changeset</literal> keyword, but forgets to give any content for it. " dongsheng@627: "When instructed to use this style file, Mercurial promptly complains." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:545 dongsheng@627: msgid "This error message looks intimidating, but it is not too hard to follow." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:549 dongsheng@627: msgid "" dongsheng@627: "The first component is simply Mercurial's way of saying <quote>I am giving " dongsheng@627: "up</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:554 dongsheng@627: msgid "Next comes the name of the style file that contains the error." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:560 dongsheng@627: msgid "" dongsheng@627: "Following the file name is the line number where the error was encountered." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:565 dongsheng@627: msgid "Finally, a description of what went wrong." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:570 dongsheng@627: msgid "" dongsheng@627: "The description of the problem is not always clear (as in this case), but " dongsheng@627: "even when it is cryptic, it is almost always trivial to visually inspect the " dongsheng@627: "offending line in the style file and see what is wrong." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:578 dongsheng@627: msgid "Uniquely identifying a repository" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:580 dongsheng@627: msgid "" dongsheng@627: "If you would like to be able to identify a Mercurial repository <quote>fairly " dongsheng@627: "uniquely</quote> using a short string as an identifier, you can use the first " dongsheng@627: "revision in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:587 dongsheng@627: msgid "" dongsheng@627: "This is not guaranteed to be unique, but it is nevertheless useful in many " dongsheng@627: "cases." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:590 dongsheng@627: msgid "" dongsheng@627: "It will not work in a completely empty repository, because such a repository " dongsheng@627: "does not have a revision zero." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:594 dongsheng@627: msgid "" dongsheng@627: "Neither will it work in the (extremely rare) case where a repository is a " dongsheng@627: "merge of two or more formerly independent repositories, and you still have " dongsheng@627: "those repositories around." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:599 dongsheng@627: msgid "Here are some uses to which you could put this identifier:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:602 dongsheng@627: msgid "" dongsheng@627: "As a key into a table for a database that manages repositories on a server." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:605 dongsheng@627: msgid "" dongsheng@627: "As half of a {<emphasis>repository ID</emphasis>, <emphasis>revision ID</" dongsheng@627: "emphasis>} tuple. Save this information away when you run an automated build " dongsheng@627: "or other activity, so that you can <quote>replay</quote> the build later if " dongsheng@627: "necessary." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch11-template.xml:614 dongsheng@627: msgid "Mimicking Subversion's output" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:616 dongsheng@627: msgid "" dongsheng@627: "Let's try to emulate the default output format used by another revision " dongsheng@627: "control tool, Subversion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:621 dongsheng@627: msgid "" dongsheng@627: "Since Subversion's output style is fairly simple, it is easy to copy-and-" dongsheng@627: "paste a hunk of its output into a file, and replace the text produced above " dongsheng@627: "by Subversion with the template values we'd like to see expanded." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:628 dongsheng@627: msgid "" dongsheng@627: "There are a few small ways in which this template deviates from the output " dongsheng@627: "produced by Subversion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:631 dongsheng@627: msgid "" dongsheng@627: "Subversion prints a <quote>readable</quote> date (the <quote><literal>Wed, 27 " dongsheng@627: "Sep 2006</literal></quote> in the example output above) in parentheses. " dongsheng@627: "Mercurial's templating engine does not provide a way to display a date in " dongsheng@627: "this format without also printing the time and time zone." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:638 dongsheng@627: msgid "" dongsheng@627: "We emulate Subversion's printing of <quote>separator</quote> lines full of " dongsheng@627: "<quote><literal>-</literal></quote> characters by ending the template with " dongsheng@627: "such a line. We use the templating engine's <literal role=\"template-keyword" dongsheng@627: "\">header</literal> keyword to print a separator line as the first line of " dongsheng@627: "output (see below), thus achieving similar output to Subversion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch11-template.xml:647 dongsheng@627: msgid "" dongsheng@627: "Subversion's output includes a count in the header of the number of lines in " dongsheng@627: "the commit message. We cannot replicate this in Mercurial; the templating " dongsheng@627: "engine does not currently provide a filter that counts the number of lines " dongsheng@627: "the template generates." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:653 dongsheng@627: msgid "" dongsheng@627: "It took me no more than a minute or two of work to replace literal text from " dongsheng@627: "an example of Subversion's output with some keywords and filters to give the " dongsheng@627: "template above. The style file simply refers to the template." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch11-template.xml:660 dongsheng@627: msgid "" dongsheng@627: "We could have included the text of the template file directly in the style " dongsheng@627: "file by enclosing it in quotes and replacing the newlines with " dongsheng@627: "<quote><literal>\\n</literal></quote> sequences, but it would have made the " dongsheng@627: "style file too difficult to read. Readability is a good guide when you're " dongsheng@627: "trying to decide whether some text belongs in a style file, or in a template " dongsheng@627: "file that the style file points to. If the style file will look too big or " dongsheng@627: "cluttered if you insert a literal piece of text, drop it into a template " dongsheng@627: "instead." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch12-mq.xml:5 dongsheng@627: msgid "Managing change with Mercurial Queues" dongsheng@627: msgstr "使用 MQ 管理修改" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:8 dongsheng@627: msgid "The patch management problem" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:10 dongsheng@627: msgid "" dongsheng@627: "Here is a common scenario: you need to install a software package from " dongsheng@627: "source, but you find a bug that you must fix in the source before you can " dongsheng@627: "start using the package. You make your changes, forget about the package for " dongsheng@627: "a while, and a few months later you need to upgrade to a newer version of the " dongsheng@627: "package. If the newer version of the package still has the bug, you must " dongsheng@627: "extract your fix from the older source tree and apply it against the newer " dongsheng@627: "version. This is a tedious task, and it's easy to make mistakes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:20 dongsheng@627: msgid "" dongsheng@627: "This is a simple case of the <quote>patch management</quote> problem. You " dongsheng@627: "have an <quote>upstream</quote> source tree that you can't change; you need " dongsheng@627: "to make some local changes on top of the upstream tree; and you'd like to be " dongsheng@627: "able to keep those changes separate, so that you can apply them to newer " dongsheng@627: "versions of the upstream source." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:27 dongsheng@627: msgid "" dongsheng@627: "The patch management problem arises in many situations. Probably the most " dongsheng@627: "visible is that a user of an open source software project will contribute a " dongsheng@627: "bug fix or new feature to the project's maintainers in the form of a patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:32 dongsheng@627: msgid "" dongsheng@627: "Distributors of operating systems that include open source software often " dongsheng@627: "need to make changes to the packages they distribute so that they will build " dongsheng@627: "properly in their environments." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:37 dongsheng@627: msgid "" dongsheng@627: "When you have few changes to maintain, it is easy to manage a single patch " dongsheng@627: "using the standard <command>diff</command> and <command>patch</command> " dongsheng@627: "programs (see section <xref linkend=\"sec.mq.patch\"/> for a discussion of " dongsheng@627: "these tools). Once the number of changes grows, it starts to make sense to " dongsheng@627: "maintain patches as discrete <quote>chunks of work,</quote> so that for " dongsheng@627: "example a single patch will contain only one bug fix (the patch might modify " dongsheng@627: "several files, but it's doing <quote>only one thing</quote>), and you may " dongsheng@627: "have a number of such patches for different bugs you need fixed and local " dongsheng@627: "changes you require. In this situation, if you submit a bug fix patch to the " dongsheng@627: "upstream maintainers of a package and they include your fix in a subsequent " dongsheng@627: "release, you can simply drop that single patch when you're updating to the " dongsheng@627: "newer release." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:52 dongsheng@627: msgid "" dongsheng@627: "Maintaining a single patch against an upstream tree is a little tedious and " dongsheng@627: "error-prone, but not difficult. However, the complexity of the problem grows " dongsheng@627: "rapidly as the number of patches you have to maintain increases. With more " dongsheng@627: "than a tiny number of patches in hand, understanding which ones you have " dongsheng@627: "applied and maintaining them moves from messy to overwhelming." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:59 dongsheng@627: msgid "" dongsheng@627: "Fortunately, Mercurial includes a powerful extension, Mercurial Queues (or " dongsheng@627: "simply <quote>MQ</quote>), that massively simplifies the patch management " dongsheng@627: "problem." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:65 dongsheng@627: msgid "The prehistory of Mercurial Queues" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:67 dongsheng@627: msgid "" dongsheng@627: "During the late 1990s, several Linux kernel developers started to maintain " dongsheng@627: "<quote>patch series</quote> that modified the behaviour of the Linux kernel. " dongsheng@627: "Some of these series were focused on stability, some on feature coverage, and " dongsheng@627: "others were more speculative." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:73 dongsheng@627: msgid "" dongsheng@627: "The sizes of these patch series grew rapidly. In 2002, Andrew Morton " dongsheng@627: "published some shell scripts he had been using to automate the task of " dongsheng@627: "managing his patch queues. Andrew was successfully using these scripts to " dongsheng@627: "manage hundreds (sometimes thousands) of patches on top of the Linux kernel." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:80 dongsheng@627: msgid "A patchwork quilt" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:82 dongsheng@627: msgid "" dongsheng@627: "In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the approach " dongsheng@627: "of Andrew's scripts and published a tool called <quote>patchwork quilt</" dongsheng@627: "quote> <citation>web:quilt</citation>, or simply <quote>quilt</quote> (see " dongsheng@627: "<citation>gruenbacher:2005</citation> for a paper describing it). Because " dongsheng@627: "quilt substantially automated patch management, it rapidly gained a large " dongsheng@627: "following among open source software developers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:91 dongsheng@627: msgid "" dongsheng@627: "Quilt manages a <emphasis>stack of patches</emphasis> on top of a directory " dongsheng@627: "tree. To begin, you tell quilt to manage a directory tree, and tell it which " dongsheng@627: "files you want to manage; it stores away the names and contents of those " dongsheng@627: "files. To fix a bug, you create a new patch (using a single command), edit " dongsheng@627: "the files you need to fix, then <quote>refresh</quote> the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:99 dongsheng@627: msgid "" dongsheng@627: "The refresh step causes quilt to scan the directory tree; it updates the " dongsheng@627: "patch with all of the changes you have made. You can create another patch on " dongsheng@627: "top of the first, which will track the changes required to modify the tree " dongsheng@627: "from <quote>tree with one patch applied</quote> to <quote>tree with two " dongsheng@627: "patches applied</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:106 dongsheng@627: msgid "" dongsheng@627: "You can <emphasis>change</emphasis> which patches are applied to the tree. " dongsheng@627: "If you <quote>pop</quote> a patch, the changes made by that patch will vanish " dongsheng@627: "from the directory tree. Quilt remembers which patches you have popped, " dongsheng@627: "though, so you can <quote>push</quote> a popped patch again, and the " dongsheng@627: "directory tree will be restored to contain the modifications in the patch. " dongsheng@627: "Most importantly, you can run the <quote>refresh</quote> command at any time, " dongsheng@627: "and the topmost applied patch will be updated. This means that you can, at " dongsheng@627: "any time, change both which patches are applied and what modifications those " dongsheng@627: "patches make." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:118 dongsheng@627: msgid "" dongsheng@627: "Quilt knows nothing about revision control tools, so it works equally well on " dongsheng@627: "top of an unpacked tarball or a Subversion working copy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:124 dongsheng@627: msgid "From patchwork quilt to Mercurial Queues" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:126 dongsheng@627: msgid "" dongsheng@627: "In mid-2005, Chris Mason took the features of quilt and wrote an extension " dongsheng@627: "that he called Mercurial Queues, which added quilt-like behaviour to " dongsheng@627: "Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:130 dongsheng@627: msgid "" dongsheng@627: "The key difference between quilt and MQ is that quilt knows nothing about " dongsheng@627: "revision control systems, while MQ is <emphasis>integrated</emphasis> into " dongsheng@627: "Mercurial. Each patch that you push is represented as a Mercurial " dongsheng@627: "changeset. Pop a patch, and the changeset goes away." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:136 dongsheng@627: msgid "" dongsheng@627: "Because quilt does not care about revision control tools, it is still a " dongsheng@627: "tremendously useful piece of software to know about for situations where you " dongsheng@627: "cannot use Mercurial and MQ." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:144 dongsheng@627: msgid "The huge advantage of MQ" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:146 dongsheng@627: msgid "" dongsheng@627: "I cannot overstate the value that MQ offers through the unification of " dongsheng@627: "patches and revision control." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:149 dongsheng@627: msgid "" dongsheng@627: "A major reason that patches have persisted in the free software and open " dongsheng@627: "source world&emdash;in spite of the availability of increasingly capable " dongsheng@627: "revision control tools over the years&emdash;is the <emphasis>agility</" dongsheng@627: "emphasis> they offer." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:155 dongsheng@627: msgid "" dongsheng@627: "Traditional revision control tools make a permanent, irreversible record of " dongsheng@627: "everything that you do. While this has great value, it's also somewhat " dongsheng@627: "stifling. If you want to perform a wild-eyed experiment, you have to be " dongsheng@627: "careful in how you go about it, or you risk leaving unneeded&emdash;or worse, " dongsheng@627: "misleading or destabilising&emdash;traces of your missteps and errors in the " dongsheng@627: "permanent revision record." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:163 dongsheng@627: msgid "" dongsheng@627: "By contrast, MQ's marriage of distributed revision control with patches makes " dongsheng@627: "it much easier to isolate your work. Your patches live on top of normal " dongsheng@627: "revision history, and you can make them disappear or reappear at will. If " dongsheng@627: "you don't like a patch, you can drop it. If a patch isn't quite as you want " dongsheng@627: "it to be, simply fix it&emdash;as many times as you need to, until you have " dongsheng@627: "refined it into the form you desire." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:171 dongsheng@627: msgid "" dongsheng@627: "As an example, the integration of patches with revision control makes " dongsheng@627: "understanding patches and debugging their effects&emdash;and their interplay " dongsheng@627: "with the code they're based on&emdash;<emphasis>enormously</emphasis> easier. " dongsheng@627: "Since every applied patch has an associated changeset, you can give <command " dongsheng@627: "role=\"hg-cmd\">hg log</command> a file name to see which changesets and " dongsheng@627: "patches affected the file. You can use the <command role=\"hg-cmd\">hg " dongsheng@627: "bisect</command> command to binary-search through all changesets and applied " dongsheng@627: "patches to see where a bug got introduced or fixed. You can use the <command " dongsheng@627: "role=\"hg-cmd\">hg annotate</command> command to see which changeset or patch " dongsheng@627: "modified a particular line of a source file. And so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:187 dongsheng@627: msgid "Understanding patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:189 dongsheng@627: msgid "" dongsheng@627: "Because MQ doesn't hide its patch-oriented nature, it is helpful to " dongsheng@627: "understand what patches are, and a little about the tools that work with them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:193 dongsheng@627: msgid "" dongsheng@627: "The traditional Unix <command>diff</command> command compares two files, and " dongsheng@627: "prints a list of differences between them. The <command>patch</command> " dongsheng@627: "command understands these differences as <emphasis>modifications</emphasis> " dongsheng@627: "to make to a file. Take a look below for a simple example of these commands " dongsheng@627: "in action." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:202 dongsheng@627: msgid "" dongsheng@627: "The type of file that <command>diff</command> generates (and <command>patch</" dongsheng@627: "command> takes as input) is called a <quote>patch</quote> or a <quote>diff</" dongsheng@627: "quote>; there is no difference between a patch and a diff. (We'll use the " dongsheng@627: "term <quote>patch</quote>, since it's more commonly used.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:208 dongsheng@627: msgid "" dongsheng@627: "A patch file can start with arbitrary text; the <command>patch</command> " dongsheng@627: "command ignores this text, but MQ uses it as the commit message when creating " dongsheng@627: "changesets. To find the beginning of the patch content, <command>patch</" dongsheng@627: "command> searches for the first line that starts with the string " dongsheng@627: "<quote><literal>diff -</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:215 dongsheng@627: msgid "" dongsheng@627: "MQ works with <emphasis>unified</emphasis> diffs (<command>patch</command> " dongsheng@627: "can accept several other diff formats, but MQ doesn't). A unified diff " dongsheng@627: "contains two kinds of header. The <emphasis>file header</emphasis> describes " dongsheng@627: "the file being modified; it contains the name of the file to modify. When " dongsheng@627: "<command>patch</command> sees a new file header, it looks for a file with " dongsheng@627: "that name to start modifying." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:223 dongsheng@627: msgid "" dongsheng@627: "After the file header comes a series of <emphasis>hunks</emphasis>. Each " dongsheng@627: "hunk starts with a header; this identifies the range of line numbers within " dongsheng@627: "the file that the hunk should modify. Following the header, a hunk starts " dongsheng@627: "and ends with a few (usually three) lines of text from the unmodified file; " dongsheng@627: "these are called the <emphasis>context</emphasis> for the hunk. If there's " dongsheng@627: "only a small amount of context between successive hunks, <command>diff</" dongsheng@627: "command> doesn't print a new hunk header; it just runs the hunks together, " dongsheng@627: "with a few lines of context between modifications." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:235 dongsheng@627: msgid "" dongsheng@627: "Each line of context begins with a space character. Within the hunk, a line " dongsheng@627: "that begins with <quote><literal>-</literal></quote> means <quote>remove this " dongsheng@627: "line,</quote> while a line that begins with <quote><literal>+</literal></" dongsheng@627: "quote> means <quote>insert this line.</quote> For example, a line that is " dongsheng@627: "modified is represented by one deletion and one insertion." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:243 dongsheng@627: msgid "" dongsheng@627: "We will return to some of the more subtle aspects of patches later (in " dongsheng@627: "section <xref linkend=\"sec.mq.adv-patch\"/>), but you should have enough " dongsheng@627: "information now to use MQ." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:250 dongsheng@627: msgid "Getting started with Mercurial Queues" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:252 dongsheng@627: msgid "" dongsheng@627: "Because MQ is implemented as an extension, you must explicitly enable before " dongsheng@627: "you can use it. (You don't need to download anything; MQ ships with the " dongsheng@627: "standard Mercurial distribution.) To enable MQ, edit your <filename role=" dongsheng@627: "\"home\">~/.hgrc</filename> file, and add the lines below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:261 dongsheng@627: msgid "" dongsheng@627: "Once the extension is enabled, it will make a number of new commands " dongsheng@627: "available. To verify that the extension is working, you can use <command " dongsheng@627: "role=\"hg-cmd\">hg help</command> to see if the <command role=\"hg-ext-mq" dongsheng@627: "\">qinit</command> command is now available." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:269 dongsheng@627: msgid "" dongsheng@627: "You can use MQ with <emphasis>any</emphasis> Mercurial repository, and its " dongsheng@627: "commands only operate within that repository. To get started, simply prepare " dongsheng@627: "the repository using the <command role=\"hg-ext-mq\">qinit</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:276 dongsheng@627: msgid "" dongsheng@627: "This command creates an empty directory called <filename role=\"special\" " dongsheng@627: "class=\"directory\">.hg/patches</filename>, where MQ will keep its metadata. " dongsheng@627: "As with many Mercurial commands, the <command role=\"hg-ext-mq\">qinit</" dongsheng@627: "command> command prints nothing if it succeeds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:283 dongsheng@627: msgid "Creating a new patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:285 dongsheng@627: msgid "" dongsheng@627: "To begin work on a new patch, use the <command role=\"hg-ext-mq\">qnew</" dongsheng@627: "command> command. This command takes one argument, the name of the patch to " dongsheng@627: "create." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:289 dongsheng@627: msgid "" dongsheng@627: "MQ will use this as the name of an actual file in the <filename role=\"special" dongsheng@627: "\" class=\"directory\">.hg/patches</filename> directory, as you can see below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:296 dongsheng@627: msgid "" dongsheng@627: "Also newly present in the <filename role=\"special\" class=\"directory\">.hg/" dongsheng@627: "patches</filename> directory are two other files, <filename role=\"special" dongsheng@627: "\">series</filename> and <filename role=\"special\">status</filename>. The " dongsheng@627: "<filename role=\"special\">series</filename> file lists all of the patches " dongsheng@627: "that MQ knows about for this repository, with one patch per line. Mercurial " dongsheng@627: "uses the <filename role=\"special\">status</filename> file for internal book-" dongsheng@627: "keeping; it tracks all of the patches that MQ has <emphasis>applied</" dongsheng@627: "emphasis> in this repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch12-mq.xml:308 dongsheng@627: msgid "" dongsheng@627: "You may sometimes want to edit the <filename role=\"special\">series</" dongsheng@627: "filename> file by hand; for example, to change the sequence in which some " dongsheng@627: "patches are applied. However, manually editing the <filename role=\"special" dongsheng@627: "\">status</filename> file is almost always a bad idea, as it's easy to " dongsheng@627: "corrupt MQ's idea of what is happening." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:317 dongsheng@627: msgid "" dongsheng@627: "Once you have created your new patch, you can edit files in the working " dongsheng@627: "directory as you usually would. All of the normal Mercurial commands, such " dongsheng@627: "as <command role=\"hg-cmd\">hg diff</command> and <command role=\"hg-cmd\">hg " dongsheng@627: "annotate</command>, work exactly as they did before." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:325 dongsheng@627: msgid "Refreshing a patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:327 dongsheng@627: msgid "" dongsheng@627: "When you reach a point where you want to save your work, use the <command " dongsheng@627: "role=\"hg-ext-mq\">qrefresh</command> command to update the patch you are " dongsheng@627: "working on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:333 dongsheng@627: msgid "" dongsheng@627: "This command folds the changes you have made in the working directory into " dongsheng@627: "your patch, and updates its corresponding changeset to contain those changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:337 dongsheng@627: msgid "" dongsheng@627: "You can run <command role=\"hg-ext-mq\">qrefresh</command> as often as you " dongsheng@627: "like, so it's a good way to <quote>checkpoint</quote> your work. Refresh " dongsheng@627: "your patch at an opportune time; try an experiment; and if the experiment " dongsheng@627: "doesn't work out, <command role=\"hg-cmd\">hg revert</command> your " dongsheng@627: "modifications back to the last time you refreshed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:348 dongsheng@627: msgid "Stacking and tracking patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:350 dongsheng@627: msgid "" dongsheng@627: "Once you have finished working on a patch, or need to work on another, you " dongsheng@627: "can use the <command role=\"hg-ext-mq\">qnew</command> command again to " dongsheng@627: "create a new patch. Mercurial will apply this patch on top of your existing " dongsheng@627: "patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:357 dongsheng@627: msgid "" dongsheng@627: "Notice that the patch contains the changes in our prior patch as part of its " dongsheng@627: "context (you can see this more clearly in the output of <command role=\"hg-cmd" dongsheng@627: "\">hg annotate</command>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:362 dongsheng@627: msgid "" dongsheng@627: "So far, with the exception of <command role=\"hg-ext-mq\">qnew</command> and " dongsheng@627: "<command role=\"hg-ext-mq\">qrefresh</command>, we've been careful to only " dongsheng@627: "use regular Mercurial commands. However, MQ provides many commands that are " dongsheng@627: "easier to use when you are thinking about patches, as illustrated below." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:372 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qseries</command> command lists every patch " dongsheng@627: "that MQ knows about in this repository, from oldest to newest (most recently " dongsheng@627: "<emphasis>created</emphasis>)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:378 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qapplied</command> command lists every patch " dongsheng@627: "that MQ has <emphasis>applied</emphasis> in this repository, again from " dongsheng@627: "oldest to newest (most recently applied)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:387 dongsheng@627: msgid "Manipulating the patch stack" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:389 dongsheng@627: msgid "" dongsheng@627: "The previous discussion implied that there must be a difference between " dongsheng@627: "<quote>known</quote> and <quote>applied</quote> patches, and there is. MQ " dongsheng@627: "can manage a patch without it being applied in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:394 dongsheng@627: msgid "" dongsheng@627: "An <emphasis>applied</emphasis> patch has a corresponding changeset in the " dongsheng@627: "repository, and the effects of the patch and changeset are visible in the " dongsheng@627: "working directory. You can undo the application of a patch using the " dongsheng@627: "<command role=\"hg-ext-mq\">qpop</command> command. MQ still <emphasis>knows " dongsheng@627: "about</emphasis>, or manages, a popped patch, but the patch no longer has a " dongsheng@627: "corresponding changeset in the repository, and the working directory does not " dongsheng@627: "contain the changes made by the patch. Figure <xref linkend=\"fig.mq.stack\"/" dongsheng@627: "> illustrates the difference between applied and tracked patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject> dongsheng@627: #: ../en/ch12-mq.xml:407 dongsheng@627: msgid "<imageobject><imagedata fileref=\"images/mq-stack.png\"/></imageobject>" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para> dongsheng@627: #: ../en/ch12-mq.xml:409 dongsheng@627: msgid "Applied and unapplied patches in the MQ patch stack" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:414 dongsheng@627: msgid "" dongsheng@627: "You can reapply an unapplied, or popped, patch using the <command role=\"hg-" dongsheng@627: "ext-mq\">qpush</command> command. This creates a new changeset to correspond " dongsheng@627: "to the patch, and the patch's changes once again become present in the " dongsheng@627: "working directory. See below for examples of <command role=\"hg-ext-mq" dongsheng@627: "\">qpop</command> and <command role=\"hg-ext-mq\">qpush</command> in action." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:423 dongsheng@627: msgid "" dongsheng@627: "Notice that once we have popped a patch or two patches, the output of " dongsheng@627: "<command role=\"hg-ext-mq\">qseries</command> remains the same, while that of " dongsheng@627: "<command role=\"hg-ext-mq\">qapplied</command> has changed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:431 dongsheng@627: msgid "Pushing and popping many patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:433 dongsheng@627: msgid "" dongsheng@627: "While <command role=\"hg-ext-mq\">qpush</command> and <command role=\"hg-ext-" dongsheng@627: "mq\">qpop</command> each operate on a single patch at a time by default, you " dongsheng@627: "can push and pop many patches in one go. The <option role=\"hg-ext-mq-cmd-" dongsheng@627: "qpush-opt\">hg -a</option> option to <command role=\"hg-ext-mq\">qpush</" dongsheng@627: "command> causes it to push all unapplied patches, while the <option role=\"hg-" dongsheng@627: "ext-mq-cmd-qpop-opt\">-a</option> option to <command role=\"hg-ext-mq\">qpop</" dongsheng@627: "command> causes it to pop all applied patches. (For some more ways to push " dongsheng@627: "and pop many patches, see section <xref linkend=\"sec.mq.perf\"/> below.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:450 dongsheng@627: msgid "Safety checks, and overriding them" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:452 dongsheng@627: msgid "" dongsheng@627: "Several MQ commands check the working directory before they do anything, and " dongsheng@627: "fail if they find any modifications. They do this to ensure that you won't " dongsheng@627: "lose any changes that you have made, but not yet incorporated into a patch. " dongsheng@627: "The example below illustrates this; the <command role=\"hg-ext-mq\">qnew</" dongsheng@627: "command> command will not create a new patch if there are outstanding " dongsheng@627: "changes, caused in this case by the <command role=\"hg-cmd\">hg add</command> " dongsheng@627: "of <filename>file3</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:464 dongsheng@627: msgid "" dongsheng@627: "Commands that check the working directory all take an <quote>I know what I'm " dongsheng@627: "doing</quote> option, which is always named <option>-f</option>. The exact " dongsheng@627: "meaning of <option>-f</option> depends on the command. For example, <command " dongsheng@627: "role=\"hg-cmd\">hg qnew <option role=\"hg-ext-mq-cmd-qnew-opt\">hg -f</" dongsheng@627: "option></command> will incorporate any outstanding changes into the new patch " dongsheng@627: "it creates, but <command role=\"hg-cmd\">hg qpop <option role=\"hg-ext-mq-cmd-" dongsheng@627: "qpop-opt\">hg -f</option></command> will revert modifications to any files " dongsheng@627: "affected by the patch that it is popping. Be sure to read the documentation " dongsheng@627: "for a command's <option>-f</option> option before you use it!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:479 dongsheng@627: msgid "Working on several patches at once" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:481 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qrefresh</command> command always refreshes " dongsheng@627: "the <emphasis>topmost</emphasis> applied patch. This means that you can " dongsheng@627: "suspend work on one patch (by refreshing it), pop or push to make a different " dongsheng@627: "patch the top, and work on <emphasis>that</emphasis> patch for a while." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:488 dongsheng@627: msgid "" dongsheng@627: "Here's an example that illustrates how you can use this ability. Let's say " dongsheng@627: "you're developing a new feature as two patches. The first is a change to the " dongsheng@627: "core of your software, and the second&emdash;layered on top of the " dongsheng@627: "first&emdash;changes the user interface to use the code you just added to the " dongsheng@627: "core. If you notice a bug in the core while you're working on the UI patch, " dongsheng@627: "it's easy to fix the core. Simply <command role=\"hg-ext-mq\">qrefresh</" dongsheng@627: "command> the UI patch to save your in-progress changes, and <command role=" dongsheng@627: "\"hg-ext-mq\">qpop</command> down to the core patch. Fix the core bug, " dongsheng@627: "<command role=\"hg-ext-mq\">qrefresh</command> the core patch, and <command " dongsheng@627: "role=\"hg-ext-mq\">qpush</command> back to the UI patch to continue where you " dongsheng@627: "left off." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:505 dongsheng@627: msgid "More about patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:507 dongsheng@627: msgid "" dongsheng@627: "MQ uses the GNU <command>patch</command> command to apply patches, so it's " dongsheng@627: "helpful to know a few more detailed aspects of how <command>patch</command> " dongsheng@627: "works, and about patches themselves." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:513 dongsheng@627: msgid "The strip count" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:515 dongsheng@627: msgid "" dongsheng@627: "If you look at the file headers in a patch, you will notice that the " dongsheng@627: "pathnames usually have an extra component on the front that isn't present in " dongsheng@627: "the actual path name. This is a holdover from the way that people used to " dongsheng@627: "generate patches (people still do this, but it's somewhat rare with modern " dongsheng@627: "revision control tools)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:522 dongsheng@627: msgid "" dongsheng@627: "Alice would unpack a tarball, edit her files, then decide that she wanted to " dongsheng@627: "create a patch. So she'd rename her working directory, unpack the tarball " dongsheng@627: "again (hence the need for the rename), and use the <option role=\"cmd-opt-diff" dongsheng@627: "\">-r</option> and <option role=\"cmd-opt-diff\">-N</option> options to " dongsheng@627: "<command>diff</command> to recursively generate a patch between the " dongsheng@627: "unmodified directory and the modified one. The result would be that the name " dongsheng@627: "of the unmodified directory would be at the front of the left-hand path in " dongsheng@627: "every file header, and the name of the modified directory would be at the " dongsheng@627: "front of the right-hand path." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:535 dongsheng@627: msgid "" dongsheng@627: "Since someone receiving a patch from the Alices of the net would be unlikely " dongsheng@627: "to have unmodified and modified directories with exactly the same names, the " dongsheng@627: "<command>patch</command> command has a <option role=\"cmd-opt-patch\">-p</" dongsheng@627: "option> option that indicates the number of leading path name components to " dongsheng@627: "strip when trying to apply a patch. This number is called the " dongsheng@627: "<emphasis>strip count</emphasis>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:543 dongsheng@627: msgid "" dongsheng@627: "An option of <quote><literal>-p1</literal></quote> means <quote>use a strip " dongsheng@627: "count of one</quote>. If <command>patch</command> sees a file name " dongsheng@627: "<filename>foo/bar/baz</filename> in a file header, it will strip " dongsheng@627: "<filename>foo</filename> and try to patch a file named <filename>bar/baz</" dongsheng@627: "filename>. (Strictly speaking, the strip count refers to the number of " dongsheng@627: "<emphasis>path separators</emphasis> (and the components that go with them ) " dongsheng@627: "to strip. A strip count of one will turn <filename>foo/bar</filename> into " dongsheng@627: "<filename>bar</filename>, but <filename>/foo/bar</filename> (notice the extra " dongsheng@627: "leading slash) into <filename>foo/bar</filename>.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:556 dongsheng@627: msgid "" dongsheng@627: "The <quote>standard</quote> strip count for patches is one; almost all " dongsheng@627: "patches contain one leading path name component that needs to be stripped. " dongsheng@627: "Mercurial's <command role=\"hg-cmd\">hg diff</command> command generates path " dongsheng@627: "names in this form, and the <command role=\"hg-cmd\">hg import</command> " dongsheng@627: "command and MQ expect patches to have a strip count of one." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:564 dongsheng@627: msgid "" dongsheng@627: "If you receive a patch from someone that you want to add to your patch queue, " dongsheng@627: "and the patch needs a strip count other than one, you cannot just <command " dongsheng@627: "role=\"hg-ext-mq\">qimport</command> the patch, because <command role=\"hg-" dongsheng@627: "ext-mq\">qimport</command> does not yet have a <literal>-p</literal> option " dongsheng@627: "(see <ulink role=\"hg-bug\" url=\"http://www.selenic.com/mercurial/bts/" dongsheng@627: "issue311\">issue 311</ulink>). Your best bet is to <command role=\"hg-ext-mq" dongsheng@627: "\">qnew</command> a patch of your own, then use <command>patch -pN</command> " dongsheng@627: "to apply their patch, followed by <command role=\"hg-cmd\">hg addremove</" dongsheng@627: "command> to pick up any files added or removed by the patch, followed by " dongsheng@627: "<command role=\"hg-ext-mq\">hg qrefresh</command>. This complexity may become " dongsheng@627: "unnecessary; see <ulink role=\"hg-bug\" url=\"http://www.selenic.com/" dongsheng@627: "mercurial/bts/issue311\">issue 311</ulink> for details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:583 dongsheng@627: msgid "Strategies for applying a patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:585 dongsheng@627: msgid "" dongsheng@627: "When <command>patch</command> applies a hunk, it tries a handful of " dongsheng@627: "successively less accurate strategies to try to make the hunk apply. This " dongsheng@627: "falling-back technique often makes it possible to take a patch that was " dongsheng@627: "generated against an old version of a file, and apply it against a newer " dongsheng@627: "version of that file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:592 dongsheng@627: msgid "" dongsheng@627: "First, <command>patch</command> tries an exact match, where the line numbers, " dongsheng@627: "the context, and the text to be modified must apply exactly. If it cannot " dongsheng@627: "make an exact match, it tries to find an exact match for the context, without " dongsheng@627: "honouring the line numbering information. If this succeeds, it prints a line " dongsheng@627: "of output saying that the hunk was applied, but at some <emphasis>offset</" dongsheng@627: "emphasis> from the original line number." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:601 dongsheng@627: msgid "" dongsheng@627: "If a context-only match fails, <command>patch</command> removes the first and " dongsheng@627: "last lines of the context, and tries a <emphasis>reduced</emphasis> context-" dongsheng@627: "only match. If the hunk with reduced context succeeds, it prints a message " dongsheng@627: "saying that it applied the hunk with a <emphasis>fuzz factor</emphasis> (the " dongsheng@627: "number after the fuzz factor indicates how many lines of context " dongsheng@627: "<command>patch</command> had to trim before the patch applied)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:610 dongsheng@627: msgid "" dongsheng@627: "When neither of these techniques works, <command>patch</command> prints a " dongsheng@627: "message saying that the hunk in question was rejected. It saves rejected " dongsheng@627: "hunks (also simply called <quote>rejects</quote>) to a file with the same " dongsheng@627: "name, and an added <filename role=\"special\">.rej</filename> extension. It " dongsheng@627: "also saves an unmodified copy of the file with a <filename role=\"special\">." dongsheng@627: "orig</filename> extension; the copy of the file without any extensions will " dongsheng@627: "contain any changes made by hunks that <emphasis>did</emphasis> apply " dongsheng@627: "cleanly. If you have a patch that modifies <filename>foo</filename> with six " dongsheng@627: "hunks, and one of them fails to apply, you will have: an unmodified " dongsheng@627: "<filename>foo.orig</filename>, a <filename>foo.rej</filename> containing one " dongsheng@627: "hunk, and <filename>foo</filename>, containing the changes made by the five " dongsheng@627: "successful hunks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:628 dongsheng@627: msgid "Some quirks of patch representation" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:630 dongsheng@627: msgid "" dongsheng@627: "There are a few useful things to know about how <command>patch</command> " dongsheng@627: "works with files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:633 dongsheng@627: msgid "" dongsheng@627: "This should already be obvious, but <command>patch</command> cannot handle " dongsheng@627: "binary files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:637 dongsheng@627: msgid "" dongsheng@627: "Neither does it care about the executable bit; it creates new files as " dongsheng@627: "readable, but not executable." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:641 dongsheng@627: msgid "" dongsheng@627: "<command>patch</command> treats the removal of a file as a diff between the " dongsheng@627: "file to be removed and the empty file. So your idea of <quote>I deleted this " dongsheng@627: "file</quote> looks like <quote>every line of this file was deleted</quote> in " dongsheng@627: "a patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:647 dongsheng@627: msgid "" dongsheng@627: "It treats the addition of a file as a diff between the empty file and the " dongsheng@627: "file to be added. So in a patch, your idea of <quote>I added this file</" dongsheng@627: "quote> looks like <quote>every line of this file was added</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:653 dongsheng@627: msgid "" dongsheng@627: "It treats a renamed file as the removal of the old name, and the addition of " dongsheng@627: "the new name. This means that renamed files have a big footprint in " dongsheng@627: "patches. (Note also that Mercurial does not currently try to infer when " dongsheng@627: "files have been renamed or copied in a patch.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:659 dongsheng@627: msgid "" dongsheng@627: "<command>patch</command> cannot represent empty files, so you cannot use a " dongsheng@627: "patch to represent the notion <quote>I added this empty file to the tree</" dongsheng@627: "quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:666 dongsheng@627: msgid "Beware the fuzz" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:668 dongsheng@627: msgid "" dongsheng@627: "While applying a hunk at an offset, or with a fuzz factor, will often be " dongsheng@627: "completely successful, these inexact techniques naturally leave open the " dongsheng@627: "possibility of corrupting the patched file. The most common cases typically " dongsheng@627: "involve applying a patch twice, or at an incorrect location in the file. If " dongsheng@627: "<command>patch</command> or <command role=\"hg-ext-mq\">qpush</command> ever " dongsheng@627: "mentions an offset or fuzz factor, you should make sure that the modified " dongsheng@627: "files are correct afterwards." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:678 dongsheng@627: msgid "" dongsheng@627: "It's often a good idea to refresh a patch that has applied with an offset or " dongsheng@627: "fuzz factor; refreshing the patch generates new context information that will " dongsheng@627: "make it apply cleanly. I say <quote>often,</quote> not <quote>always,</" dongsheng@627: "quote> because sometimes refreshing a patch will make it fail to apply " dongsheng@627: "against a different revision of the underlying files. In some cases, such as " dongsheng@627: "when you're maintaining a patch that must sit on top of multiple versions of " dongsheng@627: "a source tree, it's acceptable to have a patch apply with some fuzz, provided " dongsheng@627: "you've verified the results of the patching process in such cases." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:691 dongsheng@627: msgid "Handling rejection" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:693 dongsheng@627: msgid "" dongsheng@627: "If <command role=\"hg-ext-mq\">qpush</command> fails to apply a patch, it " dongsheng@627: "will print an error message and exit. If it has left <filename role=\"special" dongsheng@627: "\">.rej</filename> files behind, it is usually best to fix up the rejected " dongsheng@627: "hunks before you push more patches or do any further work." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:699 dongsheng@627: msgid "" dongsheng@627: "If your patch <emphasis>used to</emphasis> apply cleanly, and no longer does " dongsheng@627: "because you've changed the underlying code that your patches are based on, " dongsheng@627: "Mercurial Queues can help; see section <xref linkend=\"sec.mq.merge\"/> for " dongsheng@627: "details." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:705 dongsheng@627: msgid "" dongsheng@627: "Unfortunately, there aren't any great techniques for dealing with rejected " dongsheng@627: "hunks. Most often, you'll need to view the <filename role=\"special\">.rej</" dongsheng@627: "filename> file and edit the target file, applying the rejected hunks by hand." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:710 dongsheng@627: msgid "" dongsheng@627: "If you're feeling adventurous, Neil Brown, a Linux kernel hacker, wrote a " dongsheng@627: "tool called <command>wiggle</command> <citation>web:wiggle</citation>, which " dongsheng@627: "is more vigorous than <command>patch</command> in its attempts to make a " dongsheng@627: "patch apply." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:716 dongsheng@627: msgid "" dongsheng@627: "Another Linux kernel hacker, Chris Mason (the author of Mercurial Queues), " dongsheng@627: "wrote a similar tool called <command>mpatch</command> <citation>web:mpatch</" dongsheng@627: "citation>, which takes a simple approach to automating the application of " dongsheng@627: "hunks rejected by <command>patch</command>. The <command>mpatch</command> " dongsheng@627: "command can help with four common reasons that a hunk may be rejected:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:725 dongsheng@627: msgid "The context in the middle of a hunk has changed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:728 dongsheng@627: msgid "A hunk is missing some context at the beginning or end." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:731 dongsheng@627: msgid "" dongsheng@627: "A large hunk might apply better&emdash;either entirely or in part&emdash;if " dongsheng@627: "it was broken up into smaller hunks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:735 dongsheng@627: msgid "" dongsheng@627: "A hunk removes lines with slightly different content than those currently " dongsheng@627: "present in the file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:739 dongsheng@627: msgid "" dongsheng@627: "If you use <command>wiggle</command> or <command>mpatch</command>, you should " dongsheng@627: "be doubly careful to check your results when you're done. In fact, " dongsheng@627: "<command>mpatch</command> enforces this method of double-checking the tool's " dongsheng@627: "output, by automatically dropping you into a merge program when it has done " dongsheng@627: "its job, so that you can verify its work and finish off any remaining merges." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:751 dongsheng@627: msgid "Getting the best performance out of MQ" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:753 dongsheng@627: msgid "" dongsheng@627: "MQ is very efficient at handling a large number of patches. I ran some " dongsheng@627: "performance experiments in mid-2006 for a talk that I gave at the 2006 " dongsheng@627: "EuroPython conference <citation>web:europython</citation>. I used as my data " dongsheng@627: "set the Linux 2.6.17-mm1 patch series, which consists of 1,738 patches. I " dongsheng@627: "applied these on top of a Linux kernel repository containing all 27,472 " dongsheng@627: "revisions between Linux 2.6.12-rc2 and Linux 2.6.17." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:762 dongsheng@627: msgid "" dongsheng@627: "On my old, slow laptop, I was able to <command role=\"hg-cmd\">hg qpush " dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</option></command> all 1,738 " dongsheng@627: "patches in 3.5 minutes, and <command role=\"hg-cmd\">hg qpop <option role=" dongsheng@627: "\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> them all in 30 seconds. " dongsheng@627: "(On a newer laptop, the time to push all patches dropped to two minutes.) I " dongsheng@627: "could <command role=\"hg-ext-mq\">qrefresh</command> one of the biggest " dongsheng@627: "patches (which made 22,779 lines of changes to 287 files) in 6.6 seconds." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:773 dongsheng@627: msgid "" dongsheng@627: "Clearly, MQ is well suited to working in large trees, but there are a few " dongsheng@627: "tricks you can use to get the best performance of it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:777 dongsheng@627: msgid "" dongsheng@627: "First of all, try to <quote>batch</quote> operations together. Every time " dongsheng@627: "you run <command role=\"hg-ext-mq\">qpush</command> or <command role=\"hg-ext-" dongsheng@627: "mq\">qpop</command>, these commands scan the working directory once to make " dongsheng@627: "sure you haven't made some changes and then forgotten to run <command role=" dongsheng@627: "\"hg-ext-mq\">qrefresh</command>. On a small tree, the time that this scan " dongsheng@627: "takes is unnoticeable. However, on a medium-sized tree (containing tens of " dongsheng@627: "thousands of files), it can take a second or more." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:788 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qpush</command> and <command role=\"hg-ext-mq" dongsheng@627: "\">qpop</command> commands allow you to push and pop multiple patches at a " dongsheng@627: "time. You can identify the <quote>destination patch</quote> that you want to " dongsheng@627: "end up at. When you <command role=\"hg-ext-mq\">qpush</command> with a " dongsheng@627: "destination specified, it will push patches until that patch is at the top of " dongsheng@627: "the applied stack. When you <command role=\"hg-ext-mq\">qpop</command> to a " dongsheng@627: "destination, MQ will pop patches until the destination patch is at the top." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:798 dongsheng@627: msgid "" dongsheng@627: "You can identify a destination patch using either the name of the patch, or " dongsheng@627: "by number. If you use numeric addressing, patches are counted from zero; " dongsheng@627: "this means that the first patch is zero, the second is one, and so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:805 dongsheng@627: msgid "Updating your patches when the underlying code changes" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:808 dongsheng@627: msgid "" dongsheng@627: "It's common to have a stack of patches on top of an underlying repository " dongsheng@627: "that you don't modify directly. If you're working on changes to third-party " dongsheng@627: "code, or on a feature that is taking longer to develop than the rate of " dongsheng@627: "change of the code beneath, you will often need to sync up with the " dongsheng@627: "underlying code, and fix up any hunks in your patches that no longer apply. " dongsheng@627: "This is called <emphasis>rebasing</emphasis> your patch series." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:817 dongsheng@627: msgid "" dongsheng@627: "The simplest way to do this is to <command role=\"hg-cmd\">hg qpop <option " dongsheng@627: "role=\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> your patches, then " dongsheng@627: "<command role=\"hg-cmd\">hg pull</command> changes into the underlying " dongsheng@627: "repository, and finally <command role=\"hg-cmd\">hg qpush <option role=\"hg-" dongsheng@627: "ext-mq-cmd-qpop-opt\">hg -a</option></command> your patches again. MQ will " dongsheng@627: "stop pushing any time it runs across a patch that fails to apply during " dongsheng@627: "conflicts, allowing you to fix your conflicts, <command role=\"hg-ext-mq" dongsheng@627: "\">qrefresh</command> the affected patch, and continue pushing until you have " dongsheng@627: "fixed your entire stack." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:829 dongsheng@627: msgid "" dongsheng@627: "This approach is easy to use and works well if you don't expect changes to " dongsheng@627: "the underlying code to affect how well your patches apply. If your patch " dongsheng@627: "stack touches code that is modified frequently or invasively in the " dongsheng@627: "underlying repository, however, fixing up rejected hunks by hand quickly " dongsheng@627: "becomes tiresome." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:836 dongsheng@627: msgid "" dongsheng@627: "It's possible to partially automate the rebasing process. If your patches " dongsheng@627: "apply cleanly against some revision of the underlying repo, MQ can use this " dongsheng@627: "information to help you to resolve conflicts between your patches and a " dongsheng@627: "different revision." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:842 dongsheng@627: msgid "The process is a little involved." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:844 dongsheng@627: msgid "" dongsheng@627: "To begin, <command role=\"hg-cmd\">hg qpush -a</command> all of your patches " dongsheng@627: "on top of the revision where you know that they apply cleanly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:848 dongsheng@627: msgid "" dongsheng@627: "Save a backup copy of your patch directory using <command role=\"hg-cmd\">hg " dongsheng@627: "qsave <option role=\"hg-ext-mq-cmd-qsave-opt\">hg -e</option> <option role=" dongsheng@627: "\"hg-ext-mq-cmd-qsave-opt\">hg -c</option></command>. This prints the name " dongsheng@627: "of the directory that it has saved the patches in. It will save the patches " dongsheng@627: "to a directory called <filename role=\"special\" class=\"directory\">.hg/" dongsheng@627: "patches.N</filename>, where <literal>N</literal> is a small integer. It also " dongsheng@627: "commits a <quote>save changeset</quote> on top of your applied patches; this " dongsheng@627: "is for internal book-keeping, and records the states of the <filename role=" dongsheng@627: "\"special\">series</filename> and <filename role=\"special\">status</" dongsheng@627: "filename> files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:862 dongsheng@627: msgid "" dongsheng@627: "Use <command role=\"hg-cmd\">hg pull</command> to bring new changes into the " dongsheng@627: "underlying repository. (Don't run <command role=\"hg-cmd\">hg pull -u</" dongsheng@627: "command>; see below for why.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:867 dongsheng@627: msgid "" dongsheng@627: "Update to the new tip revision, using <command role=\"hg-cmd\">hg update " dongsheng@627: "<option role=\"hg-opt-update\">-C</option></command> to override the patches " dongsheng@627: "you have pushed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:872 dongsheng@627: msgid "" dongsheng@627: "Merge all patches using \\hgcmdargs{qpush}{<option role=\"hg-ext-mq-cmd-qpush-" dongsheng@627: "opt\">hg -m</option> <option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</" dongsheng@627: "option>}. The <option role=\"hg-ext-mq-cmd-qpush-opt\">hg -m</option> option " dongsheng@627: "to <command role=\"hg-ext-mq\">qpush</command> tells MQ to perform a three-" dongsheng@627: "way merge if the patch fails to apply." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:882 dongsheng@627: msgid "" dongsheng@627: "During the <command role=\"hg-cmd\">hg qpush <option role=\"hg-ext-mq-cmd-" dongsheng@627: "qpush-opt\">hg -m</option></command>, each patch in the <filename role=" dongsheng@627: "\"special\">series</filename> file is applied normally. If a patch applies " dongsheng@627: "with fuzz or rejects, MQ looks at the queue you <command role=\"hg-ext-mq" dongsheng@627: "\">qsave</command>d, and performs a three-way merge with the corresponding " dongsheng@627: "changeset. This merge uses Mercurial's normal merge machinery, so it may pop " dongsheng@627: "up a GUI merge tool to help you to resolve problems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:892 dongsheng@627: msgid "" dongsheng@627: "When you finish resolving the effects of a patch, MQ refreshes your patch " dongsheng@627: "based on the result of the merge." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:895 dongsheng@627: msgid "" dongsheng@627: "At the end of this process, your repository will have one extra head from the " dongsheng@627: "old patch queue, and a copy of the old patch queue will be in <filename role=" dongsheng@627: "\"special\" class=\"directory\">.hg/patches.N</filename>. You can remove the " dongsheng@627: "extra head using <command role=\"hg-cmd\">hg qpop -a -n patches.N</command> " dongsheng@627: "or <command role=\"hg-cmd\">hg strip</command>. You can delete <filename " dongsheng@627: "role=\"special\" class=\"directory\">.hg/patches.N</filename> once you are " dongsheng@627: "sure that you no longer need it as a backup." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:907 dongsheng@627: msgid "Identifying patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:909 dongsheng@627: msgid "" dongsheng@627: "MQ commands that work with patches let you refer to a patch either by using " dongsheng@627: "its name or by a number. By name is obvious enough; pass the name " dongsheng@627: "<filename>foo.patch</filename> to <command role=\"hg-ext-mq\">qpush</" dongsheng@627: "command>, for example, and it will push patches until <filename>foo.patch</" dongsheng@627: "filename> is applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:916 dongsheng@627: msgid "" dongsheng@627: "As a shortcut, you can refer to a patch using both a name and a numeric " dongsheng@627: "offset; <literal>foo.patch-2</literal> means <quote>two patches before " dongsheng@627: "<literal>foo.patch</literal></quote>, while <literal>bar.patch+4</literal> " dongsheng@627: "means <quote>four patches after <literal>bar.patch</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:922 dongsheng@627: msgid "" dongsheng@627: "Referring to a patch by index isn't much different. The first patch printed " dongsheng@627: "in the output of <command role=\"hg-ext-mq\">qseries</command> is patch zero " dongsheng@627: "(yes, it's one of those start-at-zero counting systems); the second is patch " dongsheng@627: "one; and so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:928 dongsheng@627: msgid "" dongsheng@627: "MQ also makes it easy to work with patches when you are using normal " dongsheng@627: "Mercurial commands. Every command that accepts a changeset ID will also " dongsheng@627: "accept the name of an applied patch. MQ augments the tags normally in the " dongsheng@627: "repository with an eponymous one for each applied patch. In addition, the " dongsheng@627: "special tags \\index{tags!special tag names!<literal>qbase</literal>}" dongsheng@627: "<literal>qbase</literal> and \\index{tags!special tag names!<literal>qtip</" dongsheng@627: "literal>}<literal>qtip</literal> identify the <quote>bottom-most</quote> and " dongsheng@627: "topmost applied patches, respectively." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:940 dongsheng@627: msgid "" dongsheng@627: "These additions to Mercurial's normal tagging capabilities make dealing with " dongsheng@627: "patches even more of a breeze." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:943 dongsheng@627: msgid "Want to patchbomb a mailing list with your latest series of changes?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:947 dongsheng@627: msgid "" dongsheng@627: "(Don't know what <quote>patchbombing</quote> is? See section <xref linkend=" dongsheng@627: "\"sec.hgext.patchbomb\"/>.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:950 dongsheng@627: msgid "" dongsheng@627: "Need to see all of the patches since <literal>foo.patch</literal> that have " dongsheng@627: "touched files in a subdirectory of your tree?" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><programlisting><emphasis> dongsheng@627: #: ../en/ch12-mq.xml:954 dongsheng@627: msgid "subdir" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:959 dongsheng@627: msgid "" dongsheng@627: "Because MQ makes the names of patches available to the rest of Mercurial " dongsheng@627: "through its normal internal tag machinery, you don't need to type in the " dongsheng@627: "entire name of a patch when you want to identify it by name." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:964 dongsheng@627: msgid "" dongsheng@627: "Another nice consequence of representing patch names as tags is that when you " dongsheng@627: "run the <command role=\"hg-cmd\">hg log</command> command, it will display a " dongsheng@627: "patch's name as a tag, simply as part of its normal output. This makes it " dongsheng@627: "easy to visually distinguish applied patches from underlying <quote>normal</" dongsheng@627: "quote> revisions. The following example shows a few normal Mercurial " dongsheng@627: "commands in use with applied patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:977 dongsheng@627: msgid "Useful things to know about" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:979 dongsheng@627: msgid "" dongsheng@627: "There are a number of aspects of MQ usage that don't fit tidily into sections " dongsheng@627: "of their own, but that are good to know. Here they are, in one place." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:984 dongsheng@627: msgid "" dongsheng@627: "Normally, when you <command role=\"hg-ext-mq\">qpop</command> a patch and " dongsheng@627: "<command role=\"hg-ext-mq\">qpush</command> it again, the changeset that " dongsheng@627: "represents the patch after the pop/push will have a <emphasis>different " dongsheng@627: "identity</emphasis> than the changeset that represented the hash beforehand. " dongsheng@627: "See section <xref linkend=\"sec.mqref.cmd.qpush\"/> for information as to why " dongsheng@627: "this is." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:993 dongsheng@627: msgid "" dongsheng@627: "It's not a good idea to <command role=\"hg-cmd\">hg merge</command> changes " dongsheng@627: "from another branch with a patch changeset, at least if you want to maintain " dongsheng@627: "the <quote>patchiness</quote> of that changeset and changesets below it on " dongsheng@627: "the patch stack. If you try to do this, it will appear to succeed, but MQ " dongsheng@627: "will become confused." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1004 dongsheng@627: msgid "Managing patches in a repository" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1006 dongsheng@627: msgid "" dongsheng@627: "Because MQ's <filename role=\"special\" class=\"directory\">.hg/patches</" dongsheng@627: "filename> directory resides outside a Mercurial repository's working " dongsheng@627: "directory, the <quote>underlying</quote> Mercurial repository knows nothing " dongsheng@627: "about the management or presence of patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1012 dongsheng@627: msgid "" dongsheng@627: "This presents the interesting possibility of managing the contents of the " dongsheng@627: "patch directory as a Mercurial repository in its own right. This can be a " dongsheng@627: "useful way to work. For example, you can work on a patch for a while, " dongsheng@627: "<command role=\"hg-ext-mq\">qrefresh</command> it, then <command role=\"hg-cmd" dongsheng@627: "\">hg commit</command> the current state of the patch. This lets you " dongsheng@627: "<quote>roll back</quote> to that version of the patch later on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1021 dongsheng@627: msgid "" dongsheng@627: "You can then share different versions of the same patch stack among multiple " dongsheng@627: "underlying repositories. I use this when I am developing a Linux kernel " dongsheng@627: "feature. I have a pristine copy of my kernel sources for each of several CPU " dongsheng@627: "architectures, and a cloned repository under each that contains the patches I " dongsheng@627: "am working on. When I want to test a change on a different architecture, I " dongsheng@627: "push my current patches to the patch repository associated with that kernel " dongsheng@627: "tree, pop and push all of my patches, and build and test that kernel." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1031 dongsheng@627: msgid "" dongsheng@627: "Managing patches in a repository makes it possible for multiple developers to " dongsheng@627: "work on the same patch series without colliding with each other, all on top " dongsheng@627: "of an underlying source base that they may or may not control." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1037 dongsheng@627: msgid "MQ support for patch repositories" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1039 dongsheng@627: msgid "" dongsheng@627: "MQ helps you to work with the <filename role=\"special\" class=\"directory\">." dongsheng@627: "hg/patches</filename> directory as a repository; when you prepare a " dongsheng@627: "repository for working with patches using <command role=\"hg-ext-mq\">qinit</" dongsheng@627: "command>, you can pass the <option role=\"hg-ext-mq-cmd-qinit-opt\">hg -c</" dongsheng@627: "option> option to create the <filename role=\"special\" class=\"directory\">." dongsheng@627: "hg/patches</filename> directory as a Mercurial repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch12-mq.xml:1049 dongsheng@627: msgid "" dongsheng@627: "If you forget to use the <option role=\"hg-ext-mq-cmd-qinit-opt\">hg -c</" dongsheng@627: "option> option, you can simply go into the <filename role=\"special\" class=" dongsheng@627: "\"directory\">.hg/patches</filename> directory at any time and run <command " dongsheng@627: "role=\"hg-cmd\">hg init</command>. Don't forget to add an entry for the " dongsheng@627: "<filename role=\"special\">status</filename> file to the <filename role=" dongsheng@627: "\"special\">.hgignore</filename> file, though" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch12-mq.xml:1058 dongsheng@627: msgid "" dongsheng@627: "(<command role=\"hg-cmd\">hg qinit <option role=\"hg-ext-mq-cmd-qinit-opt" dongsheng@627: "\">hg -c</option></command> does this for you automatically); you " dongsheng@627: "<emphasis>really</emphasis> don't want to manage the <filename role=\"special" dongsheng@627: "\">status</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1065 dongsheng@627: msgid "" dongsheng@627: "As a convenience, if MQ notices that the <filename class=\"directory\">.hg/" dongsheng@627: "patches</filename> directory is a repository, it will automatically <command " dongsheng@627: "role=\"hg-cmd\">hg add</command> every patch that you create and import." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1070 dongsheng@627: msgid "" dongsheng@627: "MQ provides a shortcut command, <command role=\"hg-ext-mq\">qcommit</" dongsheng@627: "command>, that runs <command role=\"hg-cmd\">hg commit</command> in the " dongsheng@627: "<filename role=\"special\" class=\"directory\">.hg/patches</filename> " dongsheng@627: "directory. This saves some bothersome typing." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1076 dongsheng@627: msgid "" dongsheng@627: "Finally, as a convenience to manage the patch directory, you can define the " dongsheng@627: "alias <command>mq</command> on Unix systems. For example, on Linux systems " dongsheng@627: "using the <command>bash</command> shell, you can include the following " dongsheng@627: "snippet in your <filename role=\"home\">~/.bashrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1086 dongsheng@627: msgid "" dongsheng@627: "You can then issue commands of the form <command>mq pull</command> from the " dongsheng@627: "main repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1091 dongsheng@627: msgid "A few things to watch out for" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1093 dongsheng@627: msgid "" dongsheng@627: "MQ's support for working with a repository full of patches is limited in a " dongsheng@627: "few small respects." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1096 dongsheng@627: msgid "" dongsheng@627: "MQ cannot automatically detect changes that you make to the patch directory. " dongsheng@627: "If you <command role=\"hg-cmd\">hg pull</command>, manually edit, or <command " dongsheng@627: "role=\"hg-cmd\">hg update</command> changes to patches or the <filename role=" dongsheng@627: "\"special\">series</filename> file, you will have to <command role=\"hg-cmd" dongsheng@627: "\">hg qpop <option role=\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> " dongsheng@627: "and then <command role=\"hg-cmd\">hg qpush <option role=\"hg-ext-mq-cmd-qpush-" dongsheng@627: "opt\">hg -a</option></command> in the underlying repository to see those " dongsheng@627: "changes show up there. If you forget to do this, you can confuse MQ's idea " dongsheng@627: "of which patches are applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1112 dongsheng@627: msgid "Third party tools for working with patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1114 dongsheng@627: msgid "" dongsheng@627: "Once you've been working with patches for a while, you'll find yourself " dongsheng@627: "hungry for tools that will help you to understand and manipulate the patches " dongsheng@627: "you're dealing with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1118 dongsheng@627: msgid "" dongsheng@627: "The <command>diffstat</command> command <citation>web:diffstat</citation> " dongsheng@627: "generates a histogram of the modifications made to each file in a patch. It " dongsheng@627: "provides a good way to <quote>get a sense of</quote> a patch&emdash;which " dongsheng@627: "files it affects, and how much change it introduces to each file and as a " dongsheng@627: "whole. (I find that it's a good idea to use <command>diffstat</command>'s " dongsheng@627: "<option role=\"cmd-opt-diffstat\">-p</option> option as a matter of course, " dongsheng@627: "as otherwise it will try to do clever things with prefixes of file names that " dongsheng@627: "inevitably confuse at least me.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1132 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"package\">patchutils</literal> package <citation>web:" dongsheng@627: "patchutils</citation> is invaluable. It provides a set of small utilities " dongsheng@627: "that follow the <quote>Unix philosophy;</quote> each does one useful thing " dongsheng@627: "with a patch. The <literal role=\"package\">patchutils</literal> command I " dongsheng@627: "use most is <command>filterdiff</command>, which extracts subsets from a " dongsheng@627: "patch file. For example, given a patch that modifies hundreds of files " dongsheng@627: "across dozens of directories, a single invocation of <command>filterdiff</" dongsheng@627: "command> can generate a smaller patch that only touches files whose names " dongsheng@627: "match a particular glob pattern. See section <xref linkend=\"mq-collab.tips." dongsheng@627: "interdiff\"/> for another example." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1148 dongsheng@627: msgid "Good ways to work with patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1150 dongsheng@627: msgid "" dongsheng@627: "Whether you are working on a patch series to submit to a free software or " dongsheng@627: "open source project, or a series that you intend to treat as a sequence of " dongsheng@627: "regular changesets when you're done, you can use some simple techniques to " dongsheng@627: "keep your work well organised." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1156 dongsheng@627: msgid "" dongsheng@627: "Give your patches descriptive names. A good name for a patch might be " dongsheng@627: "<filename>rework-device-alloc.patch</filename>, because it will immediately " dongsheng@627: "give you a hint what the purpose of the patch is. Long names shouldn't be a " dongsheng@627: "problem; you won't be typing the names often, but you <emphasis>will</" dongsheng@627: "emphasis> be running commands like <command role=\"hg-ext-mq\">qapplied</" dongsheng@627: "command> and <command role=\"hg-ext-mq\">qtop</command> over and over. Good " dongsheng@627: "naming becomes especially important when you have a number of patches to work " dongsheng@627: "with, or if you are juggling a number of different tasks and your patches " dongsheng@627: "only get a fraction of your attention." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1168 dongsheng@627: msgid "" dongsheng@627: "Be aware of what patch you're working on. Use the <command role=\"hg-ext-mq" dongsheng@627: "\">qtop</command> command and skim over the text of your patches " dongsheng@627: "frequently&emdash;for example, using <command role=\"hg-cmd\">hg tip <option " dongsheng@627: "role=\"hg-opt-tip\">-p</option></command>)&emdash;to be sure of where you " dongsheng@627: "stand. I have several times worked on and <command role=\"hg-ext-mq" dongsheng@627: "\">qrefresh</command>ed a patch other than the one I intended, and it's often " dongsheng@627: "tricky to migrate changes into the right patch after making them in the wrong " dongsheng@627: "one." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1178 dongsheng@627: msgid "" dongsheng@627: "For this reason, it is very much worth investing a little time to learn how " dongsheng@627: "to use some of the third-party tools I described in section <xref linkend=" dongsheng@627: "\"sec.mq.tools\"/>, particularly <command>diffstat</command> and " dongsheng@627: "<command>filterdiff</command>. The former will give you a quick idea of what " dongsheng@627: "changes your patch is making, while the latter makes it easy to splice hunks " dongsheng@627: "selectively out of one patch and into another." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1189 dongsheng@627: msgid "MQ cookbook" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1192 dongsheng@627: msgid "Manage <quote>trivial</quote> patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1194 dongsheng@627: msgid "" dongsheng@627: "Because the overhead of dropping files into a new Mercurial repository is so " dongsheng@627: "low, it makes a lot of sense to manage patches this way even if you simply " dongsheng@627: "want to make a few changes to a source tarball that you downloaded." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1199 dongsheng@627: msgid "" dongsheng@627: "Begin by downloading and unpacking the source tarball, and turning it into a " dongsheng@627: "Mercurial repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1204 dongsheng@627: msgid "Continue by creating a patch stack and making your changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1209 dongsheng@627: msgid "" dongsheng@627: "Let's say a few weeks or months pass, and your package author releases a new " dongsheng@627: "version. First, bring their changes into the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1215 dongsheng@627: msgid "" dongsheng@627: "The pipeline starting with <command role=\"hg-cmd\">hg locate</command> above " dongsheng@627: "deletes all files in the working directory, so that <command role=\"hg-cmd" dongsheng@627: "\">hg commit</command>'s <option role=\"hg-opt-commit\">--addremove</option> " dongsheng@627: "option can actually tell which files have really been removed in the newer " dongsheng@627: "version of the source." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1223 dongsheng@627: msgid "Finally, you can apply your patches on top of the new tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1230 dongsheng@627: msgid "Combining entire patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1232 dongsheng@627: msgid "" dongsheng@627: "MQ provides a command, <command role=\"hg-ext-mq\">qfold</command> that lets " dongsheng@627: "you combine entire patches. This <quote>folds</quote> the patches you name, " dongsheng@627: "in the order you name them, into the topmost applied patch, and concatenates " dongsheng@627: "their descriptions onto the end of its description. The patches that you " dongsheng@627: "fold must be unapplied before you fold them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1240 dongsheng@627: msgid "" dongsheng@627: "The order in which you fold patches matters. If your topmost applied patch " dongsheng@627: "is <literal>foo</literal>, and you <command role=\"hg-ext-mq\">qfold</" dongsheng@627: "command> <literal>bar</literal> and <literal>quux</literal> into it, you will " dongsheng@627: "end up with a patch that has the same effect as if you applied first " dongsheng@627: "<literal>foo</literal>, then <literal>bar</literal>, followed by " dongsheng@627: "<literal>quux</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch12-mq.xml:1251 dongsheng@627: msgid "Merging part of one patch into another" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1253 dongsheng@627: msgid "" dongsheng@627: "Merging <emphasis>part</emphasis> of one patch into another is more difficult " dongsheng@627: "than combining entire patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1257 dongsheng@627: msgid "" dongsheng@627: "If you want to move changes to entire files, you can use <command>filterdiff</" dongsheng@627: "command>'s <option role=\"cmd-opt-filterdiff\">-i</option> and <option role=" dongsheng@627: "\"cmd-opt-filterdiff\">-x</option> options to choose the modifications to " dongsheng@627: "snip out of one patch, concatenating its output onto the end of the patch you " dongsheng@627: "want to merge into. You usually won't need to modify the patch you've merged " dongsheng@627: "the changes from. Instead, MQ will report some rejected hunks when you " dongsheng@627: "<command role=\"hg-ext-mq\">qpush</command> it (from the hunks you moved into " dongsheng@627: "the other patch), and you can simply <command role=\"hg-ext-mq\">qrefresh</" dongsheng@627: "command> the patch to drop the duplicate hunks." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1270 dongsheng@627: msgid "" dongsheng@627: "If you have a patch that has multiple hunks modifying a file, and you only " dongsheng@627: "want to move a few of those hunks, the job becomes more messy, but you can " dongsheng@627: "still partly automate it. Use <command>lsdiff -nvv</command> to print some " dongsheng@627: "metadata about the patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1278 dongsheng@627: msgid "This command prints three different kinds of number:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:1281 dongsheng@627: msgid "" dongsheng@627: "(in the first column) a <emphasis>file number</emphasis> to identify each " dongsheng@627: "file modified in the patch;" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:1285 dongsheng@627: msgid "" dongsheng@627: "(on the next line, indented) the line number within a modified file where a " dongsheng@627: "hunk starts; and" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch12-mq.xml:1288 dongsheng@627: msgid "" dongsheng@627: "(on the same line) a <emphasis>hunk number</emphasis> to identify that hunk." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1292 dongsheng@627: msgid "" dongsheng@627: "You'll have to use some visual inspection, and reading of the patch, to " dongsheng@627: "identify the file and hunk numbers you'll want, but you can then pass them to " dongsheng@627: "to <command>filterdiff</command>'s <option role=\"cmd-opt-filterdiff\">--" dongsheng@627: "files</option> and <option role=\"cmd-opt-filterdiff\">--hunks</option> " dongsheng@627: "options, to select exactly the file and hunk you want to extract." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch12-mq.xml:1300 dongsheng@627: msgid "" dongsheng@627: "Once you have this hunk, you can concatenate it onto the end of your " dongsheng@627: "destination patch and continue with the remainder of section <xref linkend=" dongsheng@627: "\"sec.mq.combine\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch12-mq.xml:1307 dongsheng@627: msgid "Differences between quilt and MQ" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1309 dongsheng@627: msgid "" dongsheng@627: "If you are already familiar with quilt, MQ provides a similar command set. " dongsheng@627: "There are a few differences in the way that it works." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch12-mq.xml:1313 dongsheng@627: msgid "" dongsheng@627: "You will already have noticed that most quilt commands have MQ counterparts " dongsheng@627: "that simply begin with a <quote><literal>q</literal></quote>. The exceptions " dongsheng@627: "are quilt's <literal>add</literal> and <literal>remove</literal> commands, " dongsheng@627: "the counterparts for which are the normal Mercurial <command role=\"hg-cmd" dongsheng@627: "\">hg add</command> and <command role=\"hg-cmd\">hg remove</command> " dongsheng@627: "commands. There is no MQ equivalent of the quilt <literal>edit</literal> " dongsheng@627: "command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:5 dongsheng@627: msgid "Advanced uses of Mercurial Queues" dongsheng@627: msgstr "MQ 的高级用法" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:7 dongsheng@627: msgid "" dongsheng@627: "While it's easy to pick up straightforward uses of Mercurial Queues, use of a " dongsheng@627: "little discipline and some of MQ's less frequently used capabilities makes it " dongsheng@627: "possible to work in complicated development environments." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:12 dongsheng@627: msgid "" dongsheng@627: "In this chapter, I will use as an example a technique I have used to manage " dongsheng@627: "the development of an Infiniband device driver for the Linux kernel. The " dongsheng@627: "driver in question is large (at least as drivers go), with 25,000 lines of " dongsheng@627: "code spread across 35 source files. It is maintained by a small team of " dongsheng@627: "developers." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:18 dongsheng@627: msgid "" dongsheng@627: "While much of the material in this chapter is specific to Linux, the same " dongsheng@627: "principles apply to any code base for which you're not the primary owner, and " dongsheng@627: "upon which you need to do a lot of development." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:24 dongsheng@627: msgid "The problem of many targets" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:26 dongsheng@627: msgid "" dongsheng@627: "The Linux kernel changes rapidly, and has never been internally stable; " dongsheng@627: "developers frequently make drastic changes between releases. This means that " dongsheng@627: "a version of the driver that works well with a particular released version of " dongsheng@627: "the kernel will not even <emphasis>compile</emphasis> correctly against, " dongsheng@627: "typically, any other version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:33 dongsheng@627: msgid "" dongsheng@627: "To maintain a driver, we have to keep a number of distinct versions of Linux " dongsheng@627: "in mind." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:36 dongsheng@627: msgid "" dongsheng@627: "One target is the main Linux kernel development tree. Maintenance of the code " dongsheng@627: "is in this case partly shared by other developers in the kernel community, " dongsheng@627: "who make <quote>drive-by</quote> modifications to the driver as they develop " dongsheng@627: "and refine kernel subsystems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:42 dongsheng@627: msgid "" dongsheng@627: "We also maintain a number of <quote>backports</quote> to older versions of " dongsheng@627: "the Linux kernel, to support the needs of customers who are running older " dongsheng@627: "Linux distributions that do not incorporate our drivers. (To " dongsheng@627: "<emphasis>backport</emphasis> a piece of code is to modify it to work in an " dongsheng@627: "older version of its target environment than the version it was developed " dongsheng@627: "for.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:50 dongsheng@627: msgid "" dongsheng@627: "Finally, we make software releases on a schedule that is necessarily not " dongsheng@627: "aligned with those used by Linux distributors and kernel developers, so that " dongsheng@627: "we can deliver new features to customers without forcing them to upgrade " dongsheng@627: "their entire kernels or distributions." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:58 dongsheng@627: msgid "Tempting approaches that don't work well" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:60 dongsheng@627: msgid "" dongsheng@627: "There are two <quote>standard</quote> ways to maintain a piece of software " dongsheng@627: "that has to target many different environments." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:64 dongsheng@627: msgid "" dongsheng@627: "The first is to maintain a number of branches, each intended for a single " dongsheng@627: "target. The trouble with this approach is that you must maintain iron " dongsheng@627: "discipline in the flow of changes between repositories. A new feature or bug " dongsheng@627: "fix must start life in a <quote>pristine</quote> repository, then percolate " dongsheng@627: "out to every backport repository. Backport changes are more limited in the " dongsheng@627: "branches they should propagate to; a backport change that is applied to a " dongsheng@627: "branch where it doesn't belong will probably stop the driver from compiling." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:74 dongsheng@627: msgid "" dongsheng@627: "The second is to maintain a single source tree filled with conditional " dongsheng@627: "statements that turn chunks of code on or off depending on the intended " dongsheng@627: "target. Because these <quote>ifdefs</quote> are not allowed in the Linux " dongsheng@627: "kernel tree, a manual or automatic process must be followed to strip them out " dongsheng@627: "and yield a clean tree. A code base maintained in this fashion rapidly " dongsheng@627: "becomes a rat's nest of conditional blocks that are difficult to understand " dongsheng@627: "and maintain." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:83 dongsheng@627: msgid "" dongsheng@627: "Neither of these approaches is well suited to a situation where you don't " dongsheng@627: "<quote>own</quote> the canonical copy of a source tree. In the case of a " dongsheng@627: "Linux driver that is distributed with the standard kernel, Linus's tree " dongsheng@627: "contains the copy of the code that will be treated by the world as " dongsheng@627: "canonical. The upstream version of <quote>my</quote> driver can be modified " dongsheng@627: "by people I don't know, without me even finding out about it until after the " dongsheng@627: "changes show up in Linus's tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:93 dongsheng@627: msgid "" dongsheng@627: "These approaches have the added weakness of making it difficult to generate " dongsheng@627: "well-formed patches to submit upstream." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:97 dongsheng@627: msgid "" dongsheng@627: "In principle, Mercurial Queues seems like a good candidate to manage a " dongsheng@627: "development scenario such as the above. While this is indeed the case, MQ " dongsheng@627: "contains a few added features that make the job more pleasant." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:105 dongsheng@627: msgid "Conditionally applying patches with guards" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:107 dongsheng@627: msgid "" dongsheng@627: "Perhaps the best way to maintain sanity with so many targets is to be able to " dongsheng@627: "choose specific patches to apply for a given situation. MQ provides a " dongsheng@627: "feature called <quote>guards</quote> (which originates with quilt's " dongsheng@627: "<literal>guards</literal> command) that does just this. To start off, let's " dongsheng@627: "create a simple repository for experimenting in." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:116 dongsheng@627: msgid "" dongsheng@627: "This gives us a tiny repository that contains two patches that don't have any " dongsheng@627: "dependencies on each other, because they touch different files." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:120 dongsheng@627: msgid "" dongsheng@627: "The idea behind conditional application is that you can <quote>tag</quote> a " dongsheng@627: "patch with a <emphasis>guard</emphasis>, which is simply a text string of " dongsheng@627: "your choosing, then tell MQ to select specific guards to use when applying " dongsheng@627: "patches. MQ will then either apply, or skip over, a guarded patch, depending " dongsheng@627: "on the guards that you have selected." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:127 dongsheng@627: msgid "" dongsheng@627: "A patch can have an arbitrary number of guards; each one is " dongsheng@627: "<emphasis>positive</emphasis> (<quote>apply this patch if this guard is " dongsheng@627: "selected</quote>) or <emphasis>negative</emphasis> (<quote>skip this patch if " dongsheng@627: "this guard is selected</quote>). A patch with no guards is always applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:135 dongsheng@627: msgid "Controlling the guards on a patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:137 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qguard</command> command lets you determine " dongsheng@627: "which guards should apply to a patch, or display the guards that are already " dongsheng@627: "in effect. Without any arguments, it displays the guards on the current " dongsheng@627: "topmost patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:144 dongsheng@627: msgid "" dongsheng@627: "To set a positive guard on a patch, prefix the name of the guard with a " dongsheng@627: "<quote><literal>+</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:149 dongsheng@627: msgid "" dongsheng@627: "To set a negative guard on a patch, prefix the name of the guard with a " dongsheng@627: "<quote><literal>-</literal></quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:156 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qguard</command> command <emphasis>sets</" dongsheng@627: "emphasis> the guards on a patch; it doesn't <emphasis>modify</emphasis> " dongsheng@627: "them. What this means is that if you run <command role=\"hg-cmd\">hg qguard " dongsheng@627: "+a +b</command> on a patch, then <command role=\"hg-cmd\">hg qguard +c</" dongsheng@627: "command> on the same patch, the <emphasis>only</emphasis> guard that will be " dongsheng@627: "set on it afterwards is <literal>+c</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:165 dongsheng@627: msgid "" dongsheng@627: "Mercurial stores guards in the <filename role=\"special\">series</filename> " dongsheng@627: "file; the form in which they are stored is easy both to understand and to " dongsheng@627: "edit by hand. (In other words, you don't have to use the <command role=\"hg-" dongsheng@627: "ext-mq\">qguard</command> command if you don't want to; it's okay to simply " dongsheng@627: "edit the <filename role=\"special\">series</filename> file.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:177 dongsheng@627: msgid "Selecting the guards to use" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:179 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-mq\">qselect</command> command determines which " dongsheng@627: "guards are active at a given time. The effect of this is to determine which " dongsheng@627: "patches MQ will apply the next time you run <command role=\"hg-ext-mq" dongsheng@627: "\">qpush</command>. It has no other effect; in particular, it doesn't do " dongsheng@627: "anything to patches that are already applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:186 dongsheng@627: msgid "" dongsheng@627: "With no arguments, the <command role=\"hg-ext-mq\">qselect</command> command " dongsheng@627: "lists the guards currently in effect, one per line of output. Each argument " dongsheng@627: "is treated as the name of a guard to apply." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:193 dongsheng@627: msgid "" dongsheng@627: "In case you're interested, the currently selected guards are stored in the " dongsheng@627: "<filename role=\"special\">guards</filename> file." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:198 dongsheng@627: msgid "" dongsheng@627: "We can see the effect the selected guards have when we run <command role=\"hg-" dongsheng@627: "ext-mq\">qpush</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:203 dongsheng@627: msgid "" dongsheng@627: "A guard cannot start with a <quote><literal>+</literal></quote> or " dongsheng@627: "<quote><literal>-</literal></quote> character. The name of a guard must not " dongsheng@627: "contain white space, but most other characters are acceptable. If you try to " dongsheng@627: "use a guard with an invalid name, MQ will complain:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:212 dongsheng@627: msgid "Changing the selected guards changes the patches that are applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:217 dongsheng@627: msgid "" dongsheng@627: "You can see in the example below that negative guards take precedence over " dongsheng@627: "positive guards." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:224 dongsheng@627: msgid "MQ's rules for applying patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:226 dongsheng@627: msgid "" dongsheng@627: "The rules that MQ uses when deciding whether to apply a patch are as follows." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:229 dongsheng@627: msgid "A patch that has no guards is always applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:232 dongsheng@627: msgid "" dongsheng@627: "If the patch has any negative guard that matches any currently selected " dongsheng@627: "guard, the patch is skipped." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:235 dongsheng@627: msgid "" dongsheng@627: "If the patch has any positive guard that matches any currently selected " dongsheng@627: "guard, the patch is applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:238 dongsheng@627: msgid "" dongsheng@627: "If the patch has positive or negative guards, but none matches any currently " dongsheng@627: "selected guard, the patch is skipped." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:245 dongsheng@627: msgid "Trimming the work environment" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:247 dongsheng@627: msgid "" dongsheng@627: "In working on the device driver I mentioned earlier, I don't apply the " dongsheng@627: "patches to a normal Linux kernel tree. Instead, I use a repository that " dongsheng@627: "contains only a snapshot of the source files and headers that are relevant to " dongsheng@627: "Infiniband development. This repository is 1% the size of a kernel " dongsheng@627: "repository, so it's easier to work with." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:254 dongsheng@627: msgid "" dongsheng@627: "I then choose a <quote>base</quote> version on top of which the patches are " dongsheng@627: "applied. This is a snapshot of the Linux kernel tree as of a revision of my " dongsheng@627: "choosing. When I take the snapshot, I record the changeset ID from the " dongsheng@627: "kernel repository in the commit message. Since the snapshot preserves the " dongsheng@627: "<quote>shape</quote> and content of the relevant parts of the kernel tree, I " dongsheng@627: "can apply my patches on top of either my tiny repository or a normal kernel " dongsheng@627: "tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:263 dongsheng@627: msgid "" dongsheng@627: "Normally, the base tree atop which the patches apply should be a snapshot of " dongsheng@627: "a very recent upstream tree. This best facilitates the development of " dongsheng@627: "patches that can easily be submitted upstream with few or no modifications." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:270 dongsheng@627: msgid "Dividing up the <filename role=\"special\">series</filename> file" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:273 dongsheng@627: msgid "" dongsheng@627: "I categorise the patches in the <filename role=\"special\">series</filename> " dongsheng@627: "file into a number of logical groups. Each section of like patches begins " dongsheng@627: "with a block of comments that describes the purpose of the patches that " dongsheng@627: "follow." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:279 dongsheng@627: msgid "" dongsheng@627: "The sequence of patch groups that I maintain follows. The ordering of these " dongsheng@627: "groups is important; I'll describe why after I introduce the groups." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:283 dongsheng@627: msgid "" dongsheng@627: "The <quote>accepted</quote> group. Patches that the development team has " dongsheng@627: "submitted to the maintainer of the Infiniband subsystem, and which he has " dongsheng@627: "accepted, but which are not present in the snapshot that the tiny repository " dongsheng@627: "is based on. These are <quote>read only</quote> patches, present only to " dongsheng@627: "transform the tree into a similar state as it is in the upstream maintainer's " dongsheng@627: "repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:291 dongsheng@627: msgid "" dongsheng@627: "The <quote>rework</quote> group. Patches that I have submitted, but that the " dongsheng@627: "upstream maintainer has requested modifications to before he will accept them." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:296 dongsheng@627: msgid "" dongsheng@627: "The <quote>pending</quote> group. Patches that I have not yet submitted to " dongsheng@627: "the upstream maintainer, but which we have finished working on. These will be " dongsheng@627: "<quote>read only</quote> for a while. If the upstream maintainer accepts " dongsheng@627: "them upon submission, I'll move them to the end of the <quote>accepted</" dongsheng@627: "quote> group. If he requests that I modify any, I'll move them to the " dongsheng@627: "beginning of the <quote>rework</quote> group." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:305 dongsheng@627: msgid "" dongsheng@627: "The <quote>in progress</quote> group. Patches that are actively being " dongsheng@627: "developed, and should not be submitted anywhere yet." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:309 dongsheng@627: msgid "" dongsheng@627: "The <quote>backport</quote> group. Patches that adapt the source tree to " dongsheng@627: "older versions of the kernel tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:313 dongsheng@627: msgid "" dongsheng@627: "The <quote>do not ship</quote> group. Patches that for some reason should " dongsheng@627: "never be submitted upstream. For example, one such patch might change " dongsheng@627: "embedded driver identification strings to make it easier to distinguish, in " dongsheng@627: "the field, between an out-of-tree version of the driver and a version shipped " dongsheng@627: "by a distribution vendor." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:321 dongsheng@627: msgid "" dongsheng@627: "Now to return to the reasons for ordering groups of patches in this way. We " dongsheng@627: "would like the lowest patches in the stack to be as stable as possible, so " dongsheng@627: "that we will not need to rework higher patches due to changes in context. " dongsheng@627: "Putting patches that will never be changed first in the <filename role=" dongsheng@627: "\"special\">series</filename> file serves this purpose." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:329 dongsheng@627: msgid "" dongsheng@627: "We would also like the patches that we know we'll need to modify to be " dongsheng@627: "applied on top of a source tree that resembles the upstream tree as closely " dongsheng@627: "as possible. This is why we keep accepted patches around for a while." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:334 dongsheng@627: msgid "" dongsheng@627: "The <quote>backport</quote> and <quote>do not ship</quote> patches float at " dongsheng@627: "the end of the <filename role=\"special\">series</filename> file. The " dongsheng@627: "backport patches must be applied on top of all other patches, and the " dongsheng@627: "<quote>do not ship</quote> patches might as well stay out of harm's way." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:343 dongsheng@627: msgid "Maintaining the patch series" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:345 dongsheng@627: msgid "" dongsheng@627: "In my work, I use a number of guards to control which patches are to be " dongsheng@627: "applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:349 dongsheng@627: msgid "" dongsheng@627: "<quote>Accepted</quote> patches are guarded with <literal>accepted</" dongsheng@627: "literal>. I enable this guard most of the time. When I'm applying the " dongsheng@627: "patches on top of a tree where the patches are already present, I can turn " dongsheng@627: "this patch off, and the patches that follow it will apply cleanly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:356 dongsheng@627: msgid "" dongsheng@627: "Patches that are <quote>finished</quote>, but not yet submitted, have no " dongsheng@627: "guards. If I'm applying the patch stack to a copy of the upstream tree, I " dongsheng@627: "don't need to enable any guards in order to get a reasonably safe source tree." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:362 dongsheng@627: msgid "" dongsheng@627: "Those patches that need reworking before being resubmitted are guarded with " dongsheng@627: "<literal>rework</literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:366 dongsheng@627: msgid "" dongsheng@627: "For those patches that are still under development, I use <literal>devel</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:369 dongsheng@627: msgid "" dongsheng@627: "A backport patch may have several guards, one for each version of the kernel " dongsheng@627: "to which it applies. For example, a patch that backports a piece of code to " dongsheng@627: "2.6.9 will have a <literal>2.6.9</literal> guard." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:374 dongsheng@627: msgid "" dongsheng@627: "This variety of guards gives me considerable flexibility in determining what " dongsheng@627: "kind of source tree I want to end up with. For most situations, the " dongsheng@627: "selection of appropriate guards is automated during the build process, but I " dongsheng@627: "can manually tune the guards to use for less common circumstances." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:381 dongsheng@627: msgid "The art of writing backport patches" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:383 dongsheng@627: msgid "" dongsheng@627: "Using MQ, writing a backport patch is a simple process. All such a patch has " dongsheng@627: "to do is modify a piece of code that uses a kernel feature not present in the " dongsheng@627: "older version of the kernel, so that the driver continues to work correctly " dongsheng@627: "under that older version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:389 dongsheng@627: msgid "" dongsheng@627: "A useful goal when writing a good backport patch is to make your code look as " dongsheng@627: "if it was written for the older version of the kernel you're targeting. The " dongsheng@627: "less obtrusive the patch, the easier it will be to understand and maintain. " dongsheng@627: "If you're writing a collection of backport patches to avoid the <quote>rat's " dongsheng@627: "nest</quote> effect of lots of <literal>#ifdef</literal>s (hunks of source " dongsheng@627: "code that are only used conditionally) in your code, don't introduce version-" dongsheng@627: "dependent <literal>#ifdef</literal>s into the patches. Instead, write " dongsheng@627: "several patches, each of which makes unconditional changes, and control their " dongsheng@627: "application using guards." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:402 dongsheng@627: msgid "" dongsheng@627: "There are two reasons to divide backport patches into a distinct group, away " dongsheng@627: "from the <quote>regular</quote> patches whose effects they modify. The first " dongsheng@627: "is that intermingling the two makes it more difficult to use a tool like the " dongsheng@627: "<literal role=\"hg-ext\">patchbomb</literal> extension to automate the " dongsheng@627: "process of submitting the patches to an upstream maintainer. The second is " dongsheng@627: "that a backport patch could perturb the context in which a subsequent regular " dongsheng@627: "patch is applied, making it impossible to apply the regular patch cleanly " dongsheng@627: "<emphasis>without</emphasis> the earlier backport patch already being applied." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:417 dongsheng@627: msgid "Useful tips for developing with MQ" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:420 dongsheng@627: msgid "Organising patches in directories" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:422 dongsheng@627: msgid "" dongsheng@627: "If you're working on a substantial project with MQ, it's not difficult to " dongsheng@627: "accumulate a large number of patches. For example, I have one patch " dongsheng@627: "repository that contains over 250 patches." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:427 dongsheng@627: msgid "" dongsheng@627: "If you can group these patches into separate logical categories, you can if " dongsheng@627: "you like store them in different directories; MQ has no problems with patch " dongsheng@627: "names that contain path separators." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch13-mq-collab.xml:434 dongsheng@627: msgid "Viewing the history of a patch" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:436 dongsheng@627: msgid "" dongsheng@627: "If you're developing a set of patches over a long time, it's a good idea to " dongsheng@627: "maintain them in a repository, as discussed in section <xref linkend=\"sec.mq." dongsheng@627: "repo\"/>. If you do so, you'll quickly discover that using the <command role=" dongsheng@627: "\"hg-cmd\">hg diff</command> command to look at the history of changes to a " dongsheng@627: "patch is unworkable. This is in part because you're looking at the second " dongsheng@627: "derivative of the real code (a diff of a diff), but also because MQ adds " dongsheng@627: "noise to the process by modifying time stamps and directory names when it " dongsheng@627: "updates a patch." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:448 dongsheng@627: msgid "" dongsheng@627: "However, you can use the <literal role=\"hg-ext\">extdiff</literal> " dongsheng@627: "extension, which is bundled with Mercurial, to turn a diff of two versions of " dongsheng@627: "a patch into something readable. To do this, you will need a third-party " dongsheng@627: "package called <literal role=\"package\">patchutils</literal> <citation>web:" dongsheng@627: "patchutils</citation>. This provides a command named <command>interdiff</" dongsheng@627: "command>, which shows the differences between two diffs as a diff. Used on " dongsheng@627: "two versions of the same diff, it generates a diff that represents the diff " dongsheng@627: "from the first to the second version." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:459 dongsheng@627: msgid "" dongsheng@627: "You can enable the <literal role=\"hg-ext\">extdiff</literal> extension in " dongsheng@627: "the usual way, by adding a line to the <literal role=\"rc-extensions" dongsheng@627: "\">extensions</literal> section of your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@630: #. &example.hg-interdiff; dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:465 dongsheng@627: msgid "" dongsheng@627: "The <command>interdiff</command> command expects to be passed the names of " dongsheng@627: "two files, but the <literal role=\"hg-ext\">extdiff</literal> extension " dongsheng@627: "passes the program it runs a pair of directories, each of which can contain " dongsheng@627: "an arbitrary number of files. We thus need a small program that will run " dongsheng@627: "<command>interdiff</command> on each pair of files in these two directories. " dongsheng@627: "This program is available as <filename role=\"special\">hg-interdiff</" dongsheng@627: "filename> in the <filename class=\"directory\">examples</filename> directory " dongsheng@627: "of the source code repository that accompanies this book." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:477 dongsheng@627: msgid "" dongsheng@627: "With the <filename role=\"special\">hg-interdiff</filename> program in your " dongsheng@627: "shell's search path, you can run it as follows, from inside an MQ patch " dongsheng@627: "directory:" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:482 dongsheng@627: msgid "" dongsheng@627: "Since you'll probably want to use this long-winded command a lot, you can get " dongsheng@627: "<literal role=\"hg-ext\">hgext</literal> to make it available as a normal " dongsheng@627: "Mercurial command, again by editing your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:489 dongsheng@627: msgid "" dongsheng@627: "This directs <literal role=\"hg-ext\">hgext</literal> to make an " dongsheng@627: "<literal>interdiff</literal> command available, so you can now shorten the " dongsheng@627: "previous invocation of <command role=\"hg-ext-extdiff\">extdiff</command> to " dongsheng@627: "something a little more wieldy." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><note><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:498 dongsheng@627: msgid "" dongsheng@627: "The <command>interdiff</command> command works well only if the underlying " dongsheng@627: "files against which versions of a patch are generated remain the same. If " dongsheng@627: "you create a patch, modify the underlying files, and then regenerate the " dongsheng@627: "patch, <command>interdiff</command> may not produce useful output." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch13-mq-collab.xml:506 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">extdiff</literal> extension is useful for more " dongsheng@627: "than merely improving the presentation of MQ patches. To read more about it, " dongsheng@627: "go to section <xref linkend=\"sec.hgext.extdiff\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><title> dongsheng@627: #: ../en/ch14-hgext.xml:5 dongsheng@627: msgid "Adding functionality with extensions" dongsheng@627: msgstr "使用扩展增加功能" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch14-hgext.xml:7 dongsheng@627: msgid "" dongsheng@627: "While the core of Mercurial is quite complete from a functionality " dongsheng@627: "standpoint, it's deliberately shorn of fancy features. This approach of " dongsheng@627: "preserving simplicity keeps the software easy to deal with for both " dongsheng@627: "maintainers and users." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch14-hgext.xml:12 dongsheng@627: msgid "" dongsheng@627: "However, Mercurial doesn't box you in with an inflexible command set: you can " dongsheng@627: "add features to it as <emphasis>extensions</emphasis> (sometimes known as " dongsheng@627: "<emphasis>plugins</emphasis>). We've already discussed a few of these " dongsheng@627: "extensions in earlier chapters." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:18 dongsheng@627: msgid "" dongsheng@627: "Section <xref linkend=\"sec.tour-merge.fetch\"/> covers the <literal role=" dongsheng@627: "\"hg-ext\">fetch</literal> extension; this combines pulling new changes and " dongsheng@627: "merging them with local changes into a single command, <command role=\"hg-ext-" dongsheng@627: "fetch\">fetch</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:24 dongsheng@627: msgid "" dongsheng@627: "In chapter <xref linkend=\"chap.hook\"/>, we covered several extensions that " dongsheng@627: "are useful for hook-related functionality: <literal role=\"hg-ext\">acl</" dongsheng@627: "literal> adds access control lists; <literal role=\"hg-ext\">bugzilla</" dongsheng@627: "literal> adds integration with the Bugzilla bug tracking system; and <literal " dongsheng@627: "role=\"hg-ext\">notify</literal> sends notification emails on new changes." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:33 dongsheng@627: msgid "" dongsheng@627: "The Mercurial Queues patch management extension is so invaluable that it " dongsheng@627: "merits two chapters and an appendix all to itself. Chapter <xref linkend=" dongsheng@627: "\"chap.mq\"/> covers the basics; chapter <xref linkend=\"chap.mq-collab\"/> " dongsheng@627: "discusses advanced topics; and appendix <xref linkend=\"chap.mqref\"/> goes " dongsheng@627: "into detail on each command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><para> dongsheng@627: #: ../en/ch14-hgext.xml:43 dongsheng@627: msgid "" dongsheng@627: "In this chapter, we'll cover some of the other extensions that are available " dongsheng@627: "for Mercurial, and briefly touch on some of the machinery you'll need to know " dongsheng@627: "about if you want to write an extension of your own." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:48 dongsheng@627: msgid "" dongsheng@627: "In section <xref linkend=\"sec.hgext.inotify\"/>, we'll discuss the " dongsheng@627: "possibility of <emphasis>huge</emphasis> performance improvements using the " dongsheng@627: "<literal role=\"hg-ext\">inotify</literal> extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch14-hgext.xml:55 dongsheng@627: msgid "" dongsheng@627: "Improve performance with the <literal role=\"hg-ext\">inotify</literal> " dongsheng@627: "extension" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:58 dongsheng@627: msgid "" dongsheng@627: "Are you interested in having some of the most common Mercurial operations run " dongsheng@627: "as much as a hundred times faster? Read on!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:62 dongsheng@627: msgid "" dongsheng@627: "Mercurial has great performance under normal circumstances. For example, " dongsheng@627: "when you run the <command role=\"hg-cmd\">hg status</command> command, " dongsheng@627: "Mercurial has to scan almost every directory and file in your repository so " dongsheng@627: "that it can display file status. Many other Mercurial commands need to do " dongsheng@627: "the same work behind the scenes; for example, the <command role=\"hg-cmd\">hg " dongsheng@627: "diff</command> command uses the status machinery to avoid doing an expensive " dongsheng@627: "comparison operation on files that obviously haven't changed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:72 dongsheng@627: msgid "" dongsheng@627: "Because obtaining file status is crucial to good performance, the authors of " dongsheng@627: "Mercurial have optimised this code to within an inch of its life. However, " dongsheng@627: "there's no avoiding the fact that when you run <command role=\"hg-cmd\">hg " dongsheng@627: "status</command>, Mercurial is going to have to perform at least one " dongsheng@627: "expensive system call for each managed file to determine whether it's changed " dongsheng@627: "since the last time Mercurial checked. For a sufficiently large repository, " dongsheng@627: "this can take a long time." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:82 dongsheng@627: msgid "" dongsheng@627: "To put a number on the magnitude of this effect, I created a repository " dongsheng@627: "containing 150,000 managed files. I timed <command role=\"hg-cmd\">hg " dongsheng@627: "status</command> as taking ten seconds to run, even when <emphasis>none</" dongsheng@627: "emphasis> of those files had been modified." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:88 dongsheng@627: msgid "" dongsheng@627: "Many modern operating systems contain a file notification facility. If a " dongsheng@627: "program signs up to an appropriate service, the operating system will notify " dongsheng@627: "it every time a file of interest is created, modified, or deleted. On Linux " dongsheng@627: "systems, the kernel component that does this is called <literal>inotify</" dongsheng@627: "literal>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:95 dongsheng@627: msgid "" dongsheng@627: "Mercurial's <literal role=\"hg-ext\">inotify</literal> extension talks to the " dongsheng@627: "kernel's <literal>inotify</literal> component to optimise <command role=\"hg-" dongsheng@627: "cmd\">hg status</command> commands. The extension has two components. A " dongsheng@627: "daemon sits in the background and receives notifications from the " dongsheng@627: "<literal>inotify</literal> subsystem. It also listens for connections from a " dongsheng@627: "regular Mercurial command. The extension modifies Mercurial's behaviour so " dongsheng@627: "that instead of scanning the filesystem, it queries the daemon. Since the " dongsheng@627: "daemon has perfect information about the state of the repository, it can " dongsheng@627: "respond with a result instantaneously, avoiding the need to scan every " dongsheng@627: "directory and file in the repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:108 dongsheng@627: msgid "" dongsheng@627: "Recall the ten seconds that I measured plain Mercurial as taking to run " dongsheng@627: "<command role=\"hg-cmd\">hg status</command> on a 150,000 file repository. " dongsheng@627: "With the <literal role=\"hg-ext\">inotify</literal> extension enabled, the " dongsheng@627: "time dropped to 0.1 seconds, a factor of <emphasis>one hundred</emphasis> " dongsheng@627: "faster." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:115 dongsheng@627: msgid "Before we continue, please pay attention to some caveats." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:118 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">inotify</literal> extension is Linux-specific. " dongsheng@627: "Because it interfaces directly to the Linux kernel's <literal>inotify</" dongsheng@627: "literal> subsystem, it does not work on other operating systems." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:123 dongsheng@627: msgid "" dongsheng@627: "It should work on any Linux distribution that was released after early 2005. " dongsheng@627: "Older distributions are likely to have a kernel that lacks <literal>inotify</" dongsheng@627: "literal>, or a version of <literal>glibc</literal> that does not have the " dongsheng@627: "necessary interfacing support." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:130 dongsheng@627: msgid "" dongsheng@627: "Not all filesystems are suitable for use with the <literal role=\"hg-ext" dongsheng@627: "\">inotify</literal> extension. Network filesystems such as NFS are a non-" dongsheng@627: "starter, for example, particularly if you're running Mercurial on several " dongsheng@627: "systems, all mounting the same network filesystem. The kernel's " dongsheng@627: "<literal>inotify</literal> system has no way of knowing about changes made on " dongsheng@627: "another system. Most local filesystems (e.g. ext3, XFS, ReiserFS) should " dongsheng@627: "work fine." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:141 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">inotify</literal> extension is not yet shipped " dongsheng@627: "with Mercurial as of May 2007, so it's a little more involved to set up than " dongsheng@627: "other extensions. But the performance improvement is worth it!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:146 dongsheng@627: msgid "" dongsheng@627: "The extension currently comes in two parts: a set of patches to the Mercurial " dongsheng@627: "source code, and a library of Python bindings to the <literal>inotify</" dongsheng@627: "literal> subsystem." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch14-hgext.xml:150 dongsheng@627: msgid "" dongsheng@627: "There are <emphasis>two</emphasis> Python <literal>inotify</literal> binding " dongsheng@627: "libraries. One of them is called <literal>pyinotify</literal>, and is " dongsheng@627: "packaged by some Linux distributions as <literal>python-inotify</literal>. " dongsheng@627: "This is <emphasis>not</emphasis> the one you'll need, as it is too buggy and " dongsheng@627: "inefficient to be practical." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:157 dongsheng@627: msgid "" dongsheng@627: "To get going, it's best to already have a functioning copy of Mercurial " dongsheng@627: "installed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><note><para> dongsheng@627: #: ../en/ch14-hgext.xml:160 dongsheng@627: msgid "" dongsheng@627: "If you follow the instructions below, you'll be <emphasis>replacing</" dongsheng@627: "emphasis> and overwriting any existing installation of Mercurial that you " dongsheng@627: "might already have, using the latest <quote>bleeding edge</quote> Mercurial " dongsheng@627: "code. Don't say you weren't warned!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:167 dongsheng@627: msgid "" dongsheng@627: "Clone the Python <literal>inotify</literal> binding repository. Build and " dongsheng@627: "install it." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:175 dongsheng@627: msgid "" dongsheng@627: "Clone the <filename class=\"directory\">crew</filename> Mercurial " dongsheng@627: "repository. Clone the <literal role=\"hg-ext\">inotify</literal> patch " dongsheng@627: "repository so that Mercurial Queues will be able to apply patches to your " dongsheng@627: "cope of the <filename class=\"directory\">crew</filename> repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:188 dongsheng@627: msgid "" dongsheng@627: "Make sure that you have the Mercurial Queues extension, <literal role=\"hg-ext" dongsheng@627: "\">mq</literal>, enabled. If you've never used MQ, read section <xref " dongsheng@627: "linkend=\"sec.mq.start\"/> to get started quickly." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:194 dongsheng@627: msgid "" dongsheng@627: "Go into the <filename class=\"directory\">inotify</filename> repo, and apply " dongsheng@627: "all of the <literal role=\"hg-ext\">inotify</literal> patches using the " dongsheng@627: "<option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</option> option to the " dongsheng@627: "<command role=\"hg-ext-mq\">qpush</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:204 dongsheng@627: msgid "" dongsheng@627: "If you get an error message from <command role=\"hg-ext-mq\">qpush</command>, " dongsheng@627: "you should not continue. Instead, ask for help." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><orderedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:208 dongsheng@627: msgid "Build and install the patched version of Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:216 dongsheng@627: msgid "" dongsheng@627: "Once you've build a suitably patched version of Mercurial, all you need to do " dongsheng@627: "to enable the <literal role=\"hg-ext\">inotify</literal> extension is add an " dongsheng@627: "entry to your <filename role=\"special\"> /.hgrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:221 dongsheng@627: msgid "" dongsheng@627: "When the <literal role=\"hg-ext\">inotify</literal> extension is enabled, " dongsheng@627: "Mercurial will automatically and transparently start the status daemon the " dongsheng@627: "first time you run a command that needs status in a repository. It runs one " dongsheng@627: "status daemon per repository." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:227 dongsheng@627: msgid "" dongsheng@627: "The status daemon is started silently, and runs in the background. If you " dongsheng@627: "look at a list of running processes after you've enabled the <literal role=" dongsheng@627: "\"hg-ext\">inotify</literal> extension and run a few commands in different " dongsheng@627: "repositories, you'll thus see a few <literal>hg</literal> processes sitting " dongsheng@627: "around, waiting for updates from the kernel and queries from Mercurial." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:235 dongsheng@627: msgid "" dongsheng@627: "The first time you run a Mercurial command in a repository when you have the " dongsheng@627: "<literal role=\"hg-ext\">inotify</literal> extension enabled, it will run " dongsheng@627: "with about the same performance as a normal Mercurial command. This is " dongsheng@627: "because the status daemon needs to perform a normal status scan so that it " dongsheng@627: "has a baseline against which to apply later updates from the kernel. " dongsheng@627: "However, <emphasis>every</emphasis> subsequent command that does any kind of " dongsheng@627: "status check should be noticeably faster on repositories of even fairly " dongsheng@627: "modest size. Better yet, the bigger your repository is, the greater a " dongsheng@627: "performance advantage you'll see. The <literal role=\"hg-ext\">inotify</" dongsheng@627: "literal> daemon makes status operations almost instantaneous on repositories " dongsheng@627: "of all sizes!" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:249 dongsheng@627: msgid "" dongsheng@627: "If you like, you can manually start a status daemon using the <command role=" dongsheng@627: "\"hg-ext-inotify\">inserve</command> command. This gives you slightly finer " dongsheng@627: "control over how the daemon ought to run. This command will of course only " dongsheng@627: "be available when the <literal role=\"hg-ext\">inotify</literal> extension is " dongsheng@627: "enabled." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:256 dongsheng@627: msgid "" dongsheng@627: "When you're using the <literal role=\"hg-ext\">inotify</literal> extension, " dongsheng@627: "you should notice <emphasis>no difference at all</emphasis> in Mercurial's " dongsheng@627: "behaviour, with the sole exception of status-related commands running a whole " dongsheng@627: "lot faster than they used to. You should specifically expect that commands " dongsheng@627: "will not print different output; neither should they give different results. " dongsheng@627: "If either of these situations occurs, please report a bug." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch14-hgext.xml:267 dongsheng@627: msgid "" dongsheng@627: "Flexible diff support with the <literal role=\"hg-ext\">extdiff</literal> " dongsheng@627: "extension" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:270 dongsheng@627: msgid "" dongsheng@627: "Mercurial's built-in <command role=\"hg-cmd\">hg diff</command> command " dongsheng@627: "outputs plaintext unified diffs." dongsheng@627: msgstr "" dongsheng@627: "Mercurial 内置命令 <command role=\"hg-cmd\">hg diff</command> 的输出与统一差异" dongsheng@627: "不同。" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:275 dongsheng@627: msgid "" dongsheng@627: "If you would like to use an external tool to display modifications, you'll " dongsheng@627: "want to use the <literal role=\"hg-ext\">extdiff</literal> extension. This " dongsheng@627: "will let you use, for example, a graphical diff tool." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:280 dongsheng@627: msgid "" dongsheng@627: "The <literal role=\"hg-ext\">extdiff</literal> extension is bundled with " dongsheng@627: "Mercurial, so it's easy to set up. In the <literal role=\"rc-extensions" dongsheng@627: "\">extensions</literal> section of your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>, simply add a one-line entry to enable the extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:286 dongsheng@627: msgid "" dongsheng@627: "This introduces a command named <command role=\"hg-ext-extdiff\">extdiff</" dongsheng@627: "command>, which by default uses your system's <command>diff</command> command " dongsheng@627: "to generate a unified diff in the same form as the built-in <command role=" dongsheng@627: "\"hg-cmd\">hg diff</command> command." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:294 dongsheng@627: msgid "" dongsheng@627: "The result won't be exactly the same as with the built-in <command role=\"hg-" dongsheng@627: "cmd\">hg diff</command> variations, because the output of <command>diff</" dongsheng@627: "command> varies from one system to another, even when passed the same options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:299 dongsheng@627: msgid "" dongsheng@627: "As the <quote><literal>making snapshot</literal></quote> lines of output " dongsheng@627: "above imply, the <command role=\"hg-ext-extdiff\">extdiff</command> command " dongsheng@627: "works by creating two snapshots of your source tree. The first snapshot is " dongsheng@627: "of the source revision; the second, of the target revision or working " dongsheng@627: "directory. The <command role=\"hg-ext-extdiff\">extdiff</command> command " dongsheng@627: "generates these snapshots in a temporary directory, passes the name of each " dongsheng@627: "directory to an external diff viewer, then deletes the temporary directory. " dongsheng@627: "For efficiency, it only snapshots the directories and files that have changed " dongsheng@627: "between the two revisions." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:312 dongsheng@627: msgid "" dongsheng@627: "Snapshot directory names have the same base name as your repository. If your " dongsheng@627: "repository path is <filename class=\"directory\">/quux/bar/foo</filename>, " dongsheng@627: "then <filename class=\"directory\">foo</filename> will be the name of each " dongsheng@627: "snapshot directory. Each snapshot directory name has its changeset ID " dongsheng@627: "appended, if appropriate. If a snapshot is of revision " dongsheng@627: "<literal>a631aca1083f</literal>, the directory will be named <filename class=" dongsheng@627: "\"directory\">foo.a631aca1083f</filename>. A snapshot of the working " dongsheng@627: "directory won't have a changeset ID appended, so it would just be <filename " dongsheng@627: "class=\"directory\">foo</filename> in this example. To see what this looks " dongsheng@627: "like in practice, look again at the <command role=\"hg-ext-extdiff\">extdiff</" dongsheng@627: "command> example above. Notice that the diff has the snapshot directory " dongsheng@627: "names embedded in its header." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:328 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-extdiff\">extdiff</command> command accepts two " dongsheng@627: "important options. The <option role=\"hg-ext-extdiff-cmd-extdiff-opt\">hg -p</" dongsheng@627: "option> option lets you choose a program to view differences with, instead of " dongsheng@627: "<command>diff</command>. With the <option role=\"hg-ext-extdiff-cmd-extdiff-" dongsheng@627: "opt\">hg -o</option> option, you can change the options that <command role=" dongsheng@627: "\"hg-ext-extdiff\">extdiff</command> passes to the program (by default, these " dongsheng@627: "options are <quote><literal>-Npru</literal></quote>, which only make sense if " dongsheng@627: "you're running <command>diff</command>). In other respects, the <command " dongsheng@627: "role=\"hg-ext-extdiff\">extdiff</command> command acts similarly to the built-" dongsheng@627: "in <command role=\"hg-cmd\">hg diff</command> command: you use the same " dongsheng@627: "option names, syntax, and arguments to specify the revisions you want, the " dongsheng@627: "files you want, and so on." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: # dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:345 dongsheng@627: msgid "" dongsheng@627: "As an example, here's how to run the normal system <command>diff</command> " dongsheng@627: "command, getting it to generate context diffs (using the <option role=\"cmd-" dongsheng@627: "opt-diff\">-c</option> option) instead of unified diffs, and five lines of " dongsheng@627: "context instead of the default three (passing <literal>5</literal> as the " dongsheng@627: "argument to the <option role=\"cmd-opt-diff\">-C</option> option)." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:354 dongsheng@627: msgid "" dongsheng@627: "Launching a visual diff tool is just as easy. Here's how to launch the " dongsheng@627: "<command>kdiff3</command> viewer." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:358 dongsheng@627: msgid "" dongsheng@627: "If your diff viewing command can't deal with directories, you can easily work " dongsheng@627: "around this with a little scripting. For an example of such scripting in " dongsheng@627: "action with the <literal role=\"hg-ext\">mq</literal> extension and the " dongsheng@627: "<command>interdiff</command> command, see section <xref linkend=\"mq-collab." dongsheng@627: "tips.interdiff\"/>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch14-hgext.xml:366 dongsheng@627: msgid "Defining command aliases" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:368 dongsheng@627: msgid "" dongsheng@627: "It can be cumbersome to remember the options to both the <command role=\"hg-" dongsheng@627: "ext-extdiff\">extdiff</command> command and the diff viewer you want to use, " dongsheng@627: "so the <literal role=\"hg-ext\">extdiff</literal> extension lets you define " dongsheng@627: "<emphasis>new</emphasis> commands that will invoke your diff viewer with " dongsheng@627: "exactly the right options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:375 dongsheng@627: msgid "" dongsheng@627: "All you need to do is edit your <filename role=\"special\"> /.hgrc</" dongsheng@627: "filename>, and add a section named <literal role=\"rc-extdiff\">extdiff</" dongsheng@627: "literal>. Inside this section, you can define multiple commands. Here's how " dongsheng@627: "to add a <literal>kdiff3</literal> command. Once you've defined this, you " dongsheng@627: "can type <quote><literal>hg kdiff3</literal></quote> and the <literal role=" dongsheng@627: "\"hg-ext\">extdiff</literal> extension will run <command>kdiff3</command> for " dongsheng@627: "you." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:384 dongsheng@627: msgid "" dongsheng@627: "If you leave the right hand side of the definition empty, as above, the " dongsheng@627: "<literal role=\"hg-ext\">extdiff</literal> extension uses the name of the " dongsheng@627: "command you defined as the name of the external program to run. But these " dongsheng@627: "names don't have to be the same. Here, we define a command named " dongsheng@627: "<quote><literal>hg wibble</literal></quote>, which runs <command>kdiff3</" dongsheng@627: "command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:393 dongsheng@627: msgid "" dongsheng@627: "You can also specify the default options that you want to invoke your diff " dongsheng@627: "viewing program with. The prefix to use is <quote><literal>opts.</literal></" dongsheng@627: "quote>, followed by the name of the command to which the options apply. This " dongsheng@627: "example defines a <quote><literal>hg vimdiff</literal></quote> command that " dongsheng@627: "runs the <command>vim</command> editor's <literal>DirDiff</literal> extension." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch14-hgext.xml:406 dongsheng@627: msgid "" dongsheng@627: "Cherrypicking changes with the <literal role=\"hg-ext\">transplant</literal> " dongsheng@627: "extension" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:409 dongsheng@627: msgid "Need to have a long chat with Brendan about this." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><title> dongsheng@627: #: ../en/ch14-hgext.xml:413 dongsheng@627: msgid "" dongsheng@627: "Send changes via email with the <literal role=\"hg-ext\">patchbomb</literal> " dongsheng@627: "extension" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:416 dongsheng@627: msgid "" dongsheng@627: "Many projects have a culture of <quote>change review</quote>, in which people " dongsheng@627: "send their modifications to a mailing list for others to read and comment on " dongsheng@627: "before they commit the final version to a shared repository. Some projects " dongsheng@627: "have people who act as gatekeepers; they apply changes from other people to a " dongsheng@627: "repository to which those others don't have access." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:424 dongsheng@627: msgid "" dongsheng@627: "Mercurial makes it easy to send changes over email for review or application, " dongsheng@627: "via its <literal role=\"hg-ext\">patchbomb</literal> extension. The " dongsheng@627: "extension is so named because changes are formatted as patches, and it's " dongsheng@627: "usual to send one changeset per email message. Sending a long series of " dongsheng@627: "changes by email is thus much like <quote>bombing</quote> the recipient's " dongsheng@627: "inbox, hence <quote>patchbomb</quote>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:432 dongsheng@627: msgid "" dongsheng@627: "As usual, the basic configuration of the <literal role=\"hg-ext\">patchbomb</" dongsheng@627: "literal> extension takes just one or two lines in your <filename role=" dongsheng@627: "\"special\"> /.hgrc</filename>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:437 dongsheng@627: msgid "" dongsheng@627: "Once you've enabled the extension, you will have a new command available, " dongsheng@627: "named <command role=\"hg-ext-patchbomb\">email</command>." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:441 dongsheng@627: msgid "" dongsheng@627: "The safest and best way to invoke the <command role=\"hg-ext-patchbomb" dongsheng@627: "\">email</command> command is to <emphasis>always</emphasis> run it first " dongsheng@627: "with the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -n</option> " dongsheng@627: "option. This will show you what the command <emphasis>would</emphasis> send, " dongsheng@627: "without actually sending anything. Once you've had a quick glance over the " dongsheng@627: "changes and verified that you are sending the right ones, you can rerun the " dongsheng@627: "same command, with the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -n</" dongsheng@627: "option> option removed." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:452 dongsheng@627: msgid "" dongsheng@627: "The <command role=\"hg-ext-patchbomb\">email</command> command accepts the " dongsheng@627: "same kind of revision syntax as every other Mercurial command. For example, " dongsheng@627: "this command will send every revision between 7 and <literal>tip</literal>, " dongsheng@627: "inclusive." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:457 dongsheng@627: msgid "" dongsheng@627: "You can also specify a <emphasis>repository</emphasis> to compare with. If " dongsheng@627: "you provide a repository but no revisions, the <command role=\"hg-ext-" dongsheng@627: "patchbomb\">email</command> command will send all revisions in the local " dongsheng@627: "repository that are not present in the remote repository. If you " dongsheng@627: "additionally specify revisions or a branch name (the latter using the <option " dongsheng@627: "role=\"hg-ext-patchbomb-cmd-email-opt\">hg -b</option> option), this will " dongsheng@627: "constrain the revisions sent." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:466 dongsheng@627: msgid "" dongsheng@627: "It's perfectly safe to run the <command role=\"hg-ext-patchbomb\">email</" dongsheng@627: "command> command without the names of the people you want to send to: if you " dongsheng@627: "do this, it will just prompt you for those values interactively. (If you're " dongsheng@627: "using a Linux or Unix-like system, you should have enhanced " dongsheng@627: "<literal>readline</literal>-style editing capabilities when entering those " dongsheng@627: "headers, too, which is useful.)" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:474 dongsheng@627: msgid "" dongsheng@627: "When you are sending just one revision, the <command role=\"hg-ext-patchbomb" dongsheng@627: "\">email</command> command will by default use the first line of the " dongsheng@627: "changeset description as the subject of the single email message it sends." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><para> dongsheng@627: #: ../en/ch14-hgext.xml:479 dongsheng@627: msgid "" dongsheng@627: "If you send multiple revisions, the <command role=\"hg-ext-patchbomb\">email</" dongsheng@627: "command> command will usually send one message per changeset. It will " dongsheng@627: "preface the series with an introductory message, in which you should describe " dongsheng@627: "the purpose of the series of changes you're sending." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><title> dongsheng@627: #: ../en/ch14-hgext.xml:486 dongsheng@627: msgid "Changing the behaviour of patchbombs" dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><para> dongsheng@627: #: ../en/ch14-hgext.xml:488 dongsheng@627: msgid "" dongsheng@627: "Not every project has exactly the same conventions for sending changes in " dongsheng@627: "email; the <literal role=\"hg-ext\">patchbomb</literal> extension tries to " dongsheng@627: "accommodate a number of variations through command line options." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:494 dongsheng@627: msgid "" dongsheng@627: "You can write a subject for the introductory message on the command line " dongsheng@627: "using the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -s</option> " dongsheng@627: "option. This takes one argument, the text of the subject to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:500 dongsheng@627: msgid "" dongsheng@627: "To change the email address from which the messages originate, use the " dongsheng@627: "<option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -f</option> option. This " dongsheng@627: "takes one argument, the email address to use." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:506 dongsheng@627: msgid "" dongsheng@627: "The default behaviour is to send unified diffs (see section <xref linkend=" dongsheng@627: "\"sec.mq.patch\"/> for a description of the format), one per message. You " dongsheng@627: "can send a binary bundle instead with the <option role=\"hg-ext-patchbomb-cmd-" dongsheng@627: "email-opt\">hg -b</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:514 dongsheng@627: msgid "" dongsheng@627: "Unified diffs are normally prefaced with a metadata header. You can omit " dongsheng@627: "this, and send unadorned diffs, with the <option role=\"hg-ext-patchbomb-cmd-" dongsheng@627: "email-opt\">hg --plain</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:520 dongsheng@627: msgid "" dongsheng@627: "Diffs are normally sent <quote>inline</quote>, in the same body part as the " dongsheng@627: "description of a patch. This makes it easiest for the largest number of " dongsheng@627: "readers to quote and respond to parts of a diff, as some mail clients will " dongsheng@627: "only quote the first MIME body part in a message. If you'd prefer to send the " dongsheng@627: "description and the diff in separate body parts, use the <option role=\"hg-" dongsheng@627: "ext-patchbomb-cmd-email-opt\">hg -a</option> option." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:530 dongsheng@627: msgid "" dongsheng@627: "Instead of sending mail messages, you can write them to an <literal>mbox</" dongsheng@627: "literal>-format mail folder using the <option role=\"hg-ext-patchbomb-cmd-" dongsheng@627: "email-opt\">hg -m</option> option. That option takes one argument, the name " dongsheng@627: "of the file to write to." dongsheng@627: msgstr "" dongsheng@627: dongsheng@627: #. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para> dongsheng@627: #: ../en/ch14-hgext.xml:537 dongsheng@627: msgid "" dongsheng@627: "If you would like to add a <command>diffstat</command>-format summary to each " dongsheng@627: "patch, and one to the introductory message, use the <option role=\"hg-ext-" dongsheng@627: "patchbomb-cmd-email-opt\">hg -d</option> option. The <command>diffstat</" dongsheng@627: "command> command displays a table containing the name of each file patched, " dongsheng@627: "the number of lines affected, and a histogram showing how much each file is " dongsheng@627: "modified. This gives readers a qualitative glance at how complex a patch is." dongsheng@627: msgstr ""