[svnbook commit] r1951 - trunk/src/zh/book
rocksun
svnbook-dev at red-bean.com
Wed Jan 25 01:02:57 CST 2006
Author: rocksun
Date: Wed Jan 25 01:01:34 2006
New Revision: 1951
Added:
trunk/src/zh/book/appc.xml
- copied, changed from r1856, /trunk/src/zh/book/appd.xml
Removed:
trunk/src/zh/book/appd.xml
Modified:
trunk/src/zh/book/appa.xml
trunk/src/zh/book/appb.xml
trunk/src/zh/book/book.xml
trunk/src/zh/book/ch00.xml
trunk/src/zh/book/ch01.xml
trunk/src/zh/book/ch02.xml
trunk/src/zh/book/ch03.xml
trunk/src/zh/book/ch04.xml
trunk/src/zh/book/ch05.xml
trunk/src/zh/book/ch06.xml
trunk/src/zh/book/ch07.xml
trunk/src/zh/book/ch08.xml
trunk/src/zh/book/ch09.xml
trunk/src/zh/book/copyright.xml
trunk/src/zh/book/foreword.xml
Log:
change the structure from 1.1 to 1.2
Modified: trunk/src/zh/book/appa.xml
==============================================================================
--- trunk/src/zh/book/appa.xml (original)
+++ trunk/src/zh/book/appa.xml Wed Jan 25 01:01:34 2006
@@ -1,4 +1,4 @@
-<appendix id="svn-ap-a">
+<appendix id="svn.forcvs">
<title>Subversion对于CVS用户</title>
<simplesect>
@@ -12,12 +12,12 @@
</simplesect>
<!-- ================================================================= -->
- <!-- ======================== SECTION 1 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-1">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.revnums">
<title>修订版本号现在不同了</title>
- <para>在CVS中，修订版本号是每文件的，这是因为CVS使用RCS作为后端；每个文件都在版本库有一个对应的RCS文件，版本库几乎就是根据项目树的结构创建。
+ <para>在CVS中，修订版本号是每文件的，这是因为CVS使用RCS文件保存数据，每个文件都在版本库有一个对应的RCS文件，版本库几乎就是根据项目树的结构创建。
</para>
<para>在Subversion，版本库看起来像是一个单独的文件系统，每次提交导致一个新的文件系统；本质上，版本库是一堆树，每棵树都有一个单独的修订版本号。当有人谈论<quote>修订版本54</quote>时，他们是在讨论一个特定的树（并且间接来说，文件系统在提交54次之后的样子）。
@@ -27,14 +27,14 @@
</para>
<para>更多细节见<xref
- linkend="svn-ch-2-sect-3.2" />.</para>
+ linkend="svn.basic.in-action.revs" />.</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 2 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-2">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.directories">
<title>目录的版本</title>
<para>Subversion会记录目录树的结构，不仅仅是文件的内容。这是编写Subversion替代CVS最重要的一个原因。
@@ -69,16 +69,16 @@
<para>同样的，如果你尝试提交目录的属性修改会有一个问题，通常情况下，提交应该会提高工作目录的本地修订版本号，但是再一次，这还是一个谎言，因为这个目录还没有添加和删除发生，因为还没有更新发生。<emphasis>因此，在你的目录不是最新的时候不允许你提交属性修改。</emphasis>
</para>
- <para>关于目录版本的更多讨论见<xref linkend="svn-ch-2-sect-3.4"/>。
+ <para>关于目录版本的更多讨论见<xref linkend="svn.basic.in-action.mixedrevs"/>。
</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 3 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-3">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.disconnected">
<title>更多离线操作</title>
<para>近些年来，磁盘空间变得异常便宜和丰富，但是网络带宽还没有，因此Subversion工作拷贝为紧缺资源进行了优化。
@@ -93,7 +93,7 @@
<term><command>svn status</command></term>
<listitem>
<para>显示你所做的本地修改（见<xref
- linkend="svn-ch-3-sect-5.3.1"/>）</para>
+ linkend="svn.tour.cycle.examine.status"/>）</para>
</listitem>
</varlistentry>
@@ -101,7 +101,7 @@
<term><command>svn diff</command></term>
<listitem>
<para>显示修改的详细信息（见see <xref
- linkend="svn-ch-3-sect-5.3.2"/>）</para>
+ linkend="svn.tour.cycle.examine.diff"/>）</para>
</listitem>
</varlistentry>
@@ -109,7 +109,7 @@
<term><command>svn revert</command></term>
<listitem>
<para>删除你的本地修改（见<xref
- linkend="svn-ch-3-sect-5.3.3"/>）</para>
+ linkend="svn.tour.cycle.examine.revert"/>）</para>
</listitem>
</varlistentry>
@@ -124,15 +124,15 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 4 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-4">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.status-vs-update">
<title>区分状态和更新</title>
<para>在Subversion，我们已经设法抹去<command>cvs status</command>和<command>cvs update</command>之间的混乱。
</para>
- <para><command>cvs status</command>命令有两个目的：第一，显示用户在工作拷贝的所有本地修改，第二，显示给用户哪些文件是最新的。很不幸，因为CVS难以阅读的状态输出，许多CVS用户并没有充分利用这个命令的好处。相反，他们慢慢习惯运行<command>cvs update</command>或<command>cvs update -n</command>来快速查看区别，如果用户忘记使用<option>-n</option>选项，副作用就是将还没有准备好处理的版本库修改合并到工作拷贝。
+ <para><command>cvs status</command>命令有两个目的：第一，显示用户在工作拷贝的所有本地修改，第二，显示给用户哪些文件是最新的。很不幸，因为CVS难以阅读的状态输出，许多CVS用户并没有充分利用这个命令的好处。相反，他们慢慢习惯运行<command>cvs update</command>或<command>cvs -n update</command>来快速查看区别，如果用户忘记使用<option>-n</option>选项，副作用就是将还没有准备好处理的版本库修改合并到工作拷贝。
</para>
<para>对于Subversion，我们通过修改<command>svn status</command>的输出使之同时满足阅读和解析的需要来努力消除这种混乱，同样，<command>svn update</command>只会打印将要更新的文件信息，而<emphasis>不是</emphasis>本地修改。
@@ -169,27 +169,27 @@
</para>
<screen>
-% svn status
-M ./foo.c
-M ./bar/baz.c
+$ svn status
+M foo.c
+M bar/baz.c
</screen>
<para>如果你指定<option>--show-updates</option>（<option>-u</option>），输出会使用比较长的格式：
</para>
<screen>
-% svn status -u
-M 1047 ./foo.c
- * 1045 ./faces.html
- * - ./bloo.png
-M 1050 ./bar/baz.c
+$ svn status -u
+M 1047 foo.c
+ * 1045 faces.html
+ * bloo.png
+M 1050 bar/baz.c
Status against revision: 1066
</screen>
- <para>在这个例子里，有两个新列，如果文件或目录已经过期了，第二列会显示星号。第三列显示工作拷贝项目的修订版本号，在上面的例子里，星号表示<filename>faces.html</filename>会在更新时更新，而<filename>bloo.png</filename>是在版本库新加的文件。（<filename>bloo.png</filename>前面的<literal>-</literal>表示它不曾存在与工作拷贝。）
+ <para>在这个例子里，有两个新列，如果文件或目录已经过期了，第二列会显示星号。第三列显示工作拷贝项目的修订版本号，在上面的例子里，星号表示<filename>faces.html</filename>会在更新时更新，而<filename>bloo.png</filename>是在版本库新加的文件。（<filename>bloo.png</filename>前面的空格表示它不曾存在于工作拷贝。）
</para>
- <!-- ###TODO describe -u here as well as -uv. -u and -v use
+ <!-- ###TODO describe -v here as well as -uv. -u and -v use
different <quote>long</quote> formats and need to be
documented separately. Moreover, as you can combine -u and
-v, it needs to be explained what each of them does. As -u is
@@ -206,7 +206,7 @@
C 资源发生冲突（修改不能完全在版本库和
工作拷贝之间合并）
X 资源在工作拷贝之外（来自其他版本库，
- 见<xref linkend="svn-ch-7-sect-2.3.6" />）
+ 见<xref linkend="svn.advanced.props.special.externals" />）
? 资源不在版本控制之下
! 资源丢失或者不完整（被Subversion以外的工具删除）
</screen>
@@ -218,19 +218,19 @@
</para>
<para>关于<command>svn
- status</command>的详细讨论见<xref linkend="svn-ch-3-sect-5.3.1" />。
+ status</command>的详细讨论见<xref linkend="svn.tour.cycle.examine.status" />。
</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 5 ============================= -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-5">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.branches-and-tags">
<title>分支和标签</title>
- <para>Subversion不区分文件系统空间和<quote>分支</quote>空间；分支和标签都是普通的文件系统目录，这恐怕是CVS用户需要逾越的最大心理障碍，所有信息在<xref linkend="svn-ch-4"/>。
+ <para>Subversion不区分文件系统空间和<quote>分支</quote>空间；分支和标签都是普通的文件系统目录，这恐怕是CVS用户需要逾越的最大心理障碍，所有信息在<xref linkend="svn.branchmerge"/>。
</para>
@@ -242,9 +242,9 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 6 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-6">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.properties">
<title>元数据属性</title>
<para>Subversion的一个新特性就是你可以对文件和目录任意附加元数据（或者是<quote>属性</quote>），属性是关联在工作拷贝文件或目录的任意名称/值对。
@@ -253,39 +253,39 @@
<para>为了设置或得到一个属性名称，使用<command>svn
propset</command>和<command>svn propget</command>子命令，列出对象所有的属性，使用<command>svn proplist</command>。</para>
- <para>更多信息见<xref linkend="svn-ch-7-sect-2"/>。</para>
+ <para>更多信息见<xref linkend="svn.advanced.props"/>。</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 7 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-7">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.conflicts">
<title>冲突解决</title>
<para>CVS使用内联<quote>冲突标志</quote>来标记冲突，并且在更新时打印<literal>C</literal>。历史上讲，这导致了许多问题，因为CVS做得还不够。许多用户在它们快速闪过终端时忘记（或没有看到）<literal>C</literal>，即使出现了冲突标记，他们也经常忘记，然后提交了带有冲突标记的文件。
</para>
<para>Subversion通过让冲突更明显来解决这个问题，它记住一个文件是处于冲突状态，在你运行<command>svn resolved</command>之前不会允许你提交修改，详情见<xref
- linkend="svn-ch-3-sect-5.4"/>。
+ linkend="svn.tour.cycle.resolve"/>。
</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 8 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-8">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.binary-and-trans">
<title>二进制文件和转化</title>
- <para>在大多数情况下，Subversion比CVS更好的处理二进制文件，因为CVS使用RCS，它只可以存储二进制文件的完整拷贝，但是，从内部原理上讲，Subversion使用二进制区别算法来表示文件的区别，而不管文件是文本文件还是二进制文件。这意味着所有的文件是以微分的（压缩的）形式存放在版本库，小的区别会通过网络传输。
+ <para>在大多数情况下，Subversion比CVS更好的处理二进制文件，因为CVS使用RCS，它只可以存储二进制文件的完整拷贝，但是，Subversion使用二进制区别算法来表示文件的区别，而不管文件是文本文件还是二进制文件。这意味着所有的文件是以微分的（压缩的）形式存放在版本库。
</para>
<para>CVS用户需要使用<option>-kb</option>选项来标记二进制文件，防止数据的混淆（因为关键字解释和行结束转化），他们有时候会忘记这样做。
</para>
- <para>Subversion使用更加异想天开的方法：第一，如果你不明确的告诉它（详情见<xref
- linkend="svn-ch-7-sect-2.3.4"/>和<xref
- linkend="svn-ch-7-sect-2.3.5"/>）这样做，它不会做任何关键字或行结束转化的操作，缺省情况下Subversion会把所有的数据看作字节串，所有的储存在版本库的文件都处于未转化的状态。
+ <para>Subversion使用更加异想天开的方法—第一，如果你不明确的告诉它（详情见<xref
+ linkend="svn.advanced.props.special.keywords"/>和<xref
+ linkend="svn.advanced.props.special.eol-style"/>）这样做，它不会做任何关键字或行结束转化的操作，缺省情况下Subversion会把所有的数据看作字节串，所有的储存在版本库的文件都处于未转化的状态。
</para>
<para>第二，Subversion维护了一个内部的概念来区别一个文件是<quote>文本</quote>还是<quote>二进制</quote>文件，但这个概念<emphasis>只</emphasis>在工作拷贝非常重要，在<command>svn update</command>，Subversion会对本地修改的文本文件执行上下文的合并，但是对二进制文件不会。
@@ -297,24 +297,24 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 9 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-9">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.modules">
<title>版本化的模块</title>
<para>不像CVS，Subversion工作拷贝会意识到它检出了一个模块，这意味着如果有人修改了模块的定义（例如添加和删除组件），然后一个对<command>svn update</command>的调用会适当的更新工作拷贝，添加或删除组件。
</para>
- <para>Subversion定义了模块作为一个目录属性的目录列表：见<xref linkend="svn-ch-7-sect-3"/>。
+ <para>Subversion定义了模块作为一个目录属性的目录列表：见<xref linkend="svn.advanced.externals"/>。
</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 10 ============================= -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-10">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.auth">
<title>认证</title>
@@ -330,23 +330,19 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 11 ============================= -->
<!-- ================================================================= -->
- <sect1 id="svn-ap-a-sect-11">
+ <!-- ================================================================= -->
+ <sect1 id="svn.forcvs.convert">
<title>转化CVS版本库到Subversion</title>
<para>或许让CVS用户熟悉Subversion最好的办法就是让他们的项目继续在新系统下工作，这可以简单得通过平淡的把CVS版本库的导出数据导入到Subversion完成，或者是更加完全的方案，不仅仅包括最新数据快照，还包括所有的历史，从一个系统到另一个系统。这是一个非常困难的问题，包括推导保持原子性的修改集，转化两个系统完全不同的分支政策。但是我们还是有许多工具声称至少部分具备了的转化已存在的CVS版本库为Subversion版本库的能力。
</para>
- <para>其中一个工具是cvs2svn（<systemitem
- class="url">http://cvs2svn.tigris.org/</systemitem>），是一个Python脚本，最初是Subversion自己的开发社区的成员编写的。其他的如Chia-liang Kao的Subversion的VCP工具（<systemitem
- class="url">http://svn.clkao.org/revml/branches/svn-perl/</systemitem>）转化器插件，还有Lev Serebryakov的RefineCVS（<systemitem
- class="url">http://lev.serebryakov.spb.ru/refinecvs/</systemitem>）。这些工具具备不同程度的完成性，也许会具备完全不同的处理CVS历史的方法。无论你决定使用哪个工具，确定要执行尽可能多的验证来确定你可以接受转化结果—毕竟，你曾经努力创建这些历史！
+ <para>其中一个工具是cvs2svn（<ulink url="http://cvs2svn.tigris.org/"/>），是一个Python脚本，最初是Subversion自己的开发社区的成员编写的。其他的如Chia-liang Kao的Subversion的VCP工具（<ulink url="http://svn.clkao.org/revml/branches/svn-perl/"/>）转化器插件，还有Lev Serebryakov的RefineCVS（<ulink url="http://lev.serebryakov.spb.ru/refinecvs/"/>）。这些工具具备不同程度的完成性，也许会具备完全不同的处理CVS历史的方法。无论你决定使用哪个工具，确定要执行尽可能多的验证来确定你可以接受转化结果—毕竟，你曾经努力创建这些历史！
</para>
- <para>关于最新的转化工具链接列表，可以访问Subversion的网站（<systemitem
- class="url">http://subversion.tigris.org/project_links.html</systemitem>）。
+ <para>关于最新的转化工具链接列表，可以访问Subversion的网站（<ulink url="http://subversion.tigris.org/project_links.html"/>）。
</para>
</sect1>
Modified: trunk/src/zh/book/appb.xml
==============================================================================
--- trunk/src/zh/book/appb.xml (original)
+++ trunk/src/zh/book/appb.xml Wed Jan 25 01:01:34 2006
@@ -1,4 +1,4 @@
-<appendix id="svn-ap-c">
+<appendix id="svn.webdav">
<title>WebDAV和自动版本化</title>
<simplesect>
@@ -11,27 +11,40 @@
</simplesect>
- <sect1 id="svn-ap-c-sect-1">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.webdav.basic">
<title>WebDAV基本概念</title>
<para>这个小节提供了对WebDAV背后思想的一个非常简短和普通的总体看法，为理解WebDAV在客户端和服务器之间的兼容性问题打下基础。
</para>
- <sect2 id="svn-ap-c-sect-1.1">
- <title>仅是平常的WebDAV</title>
+ <!-- =============================================================== -->
+ <sect2 id="svn.webdav.basic.original">
+ <title>最初的WebDAV</title>
- <para>RFC 2518为HTTP 1.1定义了一组概念和附加扩展方法来把web变成一个更加普遍的读/写媒体，基本思想是一个WebDAV兼容的web服务器可以像普通的文件服务器一样工作；客户端可以装配类似于NFS或SMB的WebDAV<quote>共享</quote>。
+ <para>RFC 2518为HTTP 1.1定义了一组概念和附加扩展方法来把web变成一个更加普遍的读/写媒体，基本思想是一个WebDAV兼容的web服务器可以像普通的文件服务器一样工作；客户端可以装配类似于NFS或SMB的WebDAV共享文件夹。
</para>
- <para>然而，必须注意到RFC 2518并<emphasis>没有</emphasis>提供任何版本控制模型，尽管DAV中有<quote>V</quote>。基本的DAV客户端和服务器只是假定每个文件或目录只有一个版本存在，可以重复的覆盖。<footnote><para>因为这个原因，一些人开玩笑说WebDAV的客户端是<quote>WebDA</quote>客户端！
+ <para>悲惨的是，WebDAV规范RFC 2518并<emphasis>没有</emphasis>提供任何版本控制模型，尽管DAV中有<quote>V</quote>。基本的DAV客户端和服务器只是假定每个文件或目录只有一个版本存在，可以重复的覆盖。<footnote><para>因为这个原因，一些人开玩笑说WebDAV的客户端是<quote>WebDA</quote>客户端！
</para></footnote></para>
- <para>这是基本的WebDAV引入的新概念和方法：
+ <para>这是基本的WebDAV引入的概念和术语：
</para>
<variablelist>
<varlistentry>
+ <term>Resources</term>
+ <listitem>
+ <para> WebDAV lingo refers to any server-side object
+ (that can be described with a URI) as a
+ <firstterm>resource</firstterm>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>新的写方法</term>
<listitem>
<para>超出了标准HTTP的<literal>PUT</literal>方法（用来创建和覆盖web资源），WebDAV定义了新的<literal>COPY</literal>和<literal>MOVE</literal>方法用来复制或重新组织资源。
@@ -42,7 +55,7 @@
<varlistentry>
<term>集合</term>
<listitem>
- <para>这是一个简单的WebDAV术语用来表示一组资源（URI），在大多数情况下，你可以说以<quote>/</quote>结尾的东西是一个集合，文件资源可以使用<literal>PUT</literal>方法写或创建，而集合资源使用<literal>MKCOL</literal>方法创建。
+ <para><firstterm>collection</firstterm>是一个简单的WebDAV术语用来表示一组资源，在大多数情况下可以看作一个目录，文件资源可以使用<literal>PUT</literal>方法写或创建，而集合资源使用<literal>MKCOL</literal>方法创建。
</para>
</listitem>
</varlistentry>
@@ -50,7 +63,7 @@
<varlistentry>
<term>属性</term>
<listitem>
- <para>这与Subversion中是同一个思想—附加在文件和集合上的元数据，一个客户端可以使用新方法<literal>PROPFIND</literal>列出或检索附加在一个资源上的属性，也可以使用<literal>PROPPATCH</literal>方法修改这些属性。一些属性是完全由用户控制的（例如，一个<quote>color</quote>属性），还有一些是WebDAV服务器创建和控制的（例如，一个保存文件最后修改时间的属性）。前一种叫做<quote>dead</quote>属性，后一种叫做<quote>live</quote>属性。
+ <para>这与Subversion中是同一个思想—附加在文件和集合上的元数据，一个客户端可以使用新方法<literal>PROPFIND</literal>列出或检索附加在一个资源上的属性，也可以使用<literal>PROPPATCH</literal>方法修改这些属性。一些属性是完全由用户控制的（例如，一个<quote>color</quote>属性），还有一些是WebDAV服务器创建和控制的（例如，一个保存文件最后修改时间的属性）。前一种叫做<quote>dead属性</quote>，后一种叫做<quote>live属性</quote>。
</para>
</listitem>
</varlistentry>
@@ -58,22 +71,33 @@
<varlistentry>
<term>锁定</term>
<listitem>
- <para>WebDAV服务器可以决定为客户端提供一个锁定特性—这部分的规范是可选的，尽管大多数WebDAV服务器提供了这个特性。如果提供这个特性，客户端可以使用新的<literal>LOCK</literal>和<literal>UNLOCK</literal>方法来调节访问资源的过程，在大多数情况下是使用独占写锁（在<xref linkend="svn-ch-2-sect-2.2"/>讨论的），尽管共享写锁也是可以的。
+ <para>WebDAV服务器可以决定为客户端提供一个锁定特性—这部分的规范是可选的，尽管大多数WebDAV服务器提供了这个特性。如果提供这个特性，客户端可以使用新的<literal>LOCK</literal>和<literal>UNLOCK</literal>方法来调节访问资源的过程，在大多数情况下是使用独占写锁（在<xref linkend="svn.basic.vsn-models.lock-unlock"/>讨论的），尽管在一些服务器实现里共享写锁也是可以的。
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>Access control</term>
+ <listitem>
+ <para>A more recent specification (RFC 3744) defines a
+ system for defining access control lists (ACLs) on
+ WebDAV resources. Some clients and servers have begun
+ to implement this feature.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect2>
- <sect2 id="svn-ap-c-sect-1.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.webdav.basic.deltav">
<title>DeltaV扩展</title>
- <para>因为RFC 2518漏下了版本概念，另一个小组留下来负责撰写RFC 3253来添加WebDAV的版本化。WebDAV/DeltaV客户端和服务器经常叫做<quote>DeltaV</quote>客户端和服务器，因为DeltaV暗含了基本的WebDAV。
+ <para>因为RFC 2518漏下了版本概念，另一个委员会留下来负责撰写RFC 3253来添加WebDAV的版本化，也就是<quote>DeltaV</quote>。WebDAV/DeltaV客户端和服务器经常叫做<quote>DeltaV</quote>客户端和服务器，因为DeltaV暗含了基本的WebDAV。
</para>
- <para>DeltaV引入了完全的新的首字母缩写，但并不是被逼迫的。想法相当的直接，如下是DeltaV引入的新概念和方法：
+ <para>DeltaV引入了完全的新的首字母缩写，但并不是被逼迫的，想法相当的直接：
</para>
<variablelist>
@@ -81,7 +105,7 @@
<varlistentry>
<term>每资源的版本化</term>
<listitem>
- <para>像CVS和其他版本控制系统，DeltaV假定每个资源有一个潜在的无穷的状态，一个客户端可以使用<literal>VERSION-CONTROL</literal>放置一个版本控制之下的资源，这创建了一个新的版本控制资源（VCR），每次你修改VCR（通过<literal>PUT</literal>、<literal>PROPPATCH</literal>等），这个资源的新状态就会创建，叫做一个版本资源（Version Resource，VR）。VCR和VR还是普通的web资源，使用URL定义，特定的VR也会拥有易读的名字。
+ <para>像CVS和其他版本控制系统，DeltaV假定每个资源有一个潜在的无穷的状态，一个客户端可以使用<literal>VERSION-CONTROL</literal>放置一个版本控制之下的资源。
</para>
</listitem>
</varlistentry>
@@ -89,7 +113,7 @@
<varlistentry>
<term>服务器端的工作拷贝模型</term>
<listitem>
- <para>一些DeltaV服务器支持在服务器创建虚拟<quote>工作区</quote>，所有的工作在这里执行。客户端使用<literal>MKWORKSPACE</literal>方法来创建私有区域，然后他们说明修改特定的VCR，<quote>把它们检出到</quote>工作拷贝，编辑，然后再次<quote>检入</quote>。在HTTP术语里，方法的顺序可能是<literal>CHECKOUT</literal>、<literal>PUT</literal>、<literal>CHECKIN</literal>，会创建一个新的VR，每个VCR也有一个<quote>历史</quote>资源用来追踪和排序它的各种VR状态。
+ <para>一些DeltaV服务器支持在服务器创建虚拟工作区，所有的工作在这里执行。客户端使用<literal>MKWORKSPACE</literal>方法来创建私有区域，然后他们说明修改特定的资源，<quote>把它们检出到</quote>工作区，编辑，然后再次<quote>检入</quote>。在HTTP术语里，方法的顺序可能是<literal>CHECKOUT</literal>、<literal>PUT</literal>、<literal>CHECKIN</literal>。
</para>
</listitem>
</varlistentry>
@@ -97,7 +121,7 @@
<varlistentry>
<term>客户端工作拷贝模型</term>
<listitem>
- <para>一些DeltaV服务器也支持客户端可以有完全特定VR的私有工作拷贝的思想，（这就是CVS和Subversion的工作原理。）当客户端希望提交修改到服务器，它通过使用<literal>MKACTIVITY</literal>方法创建一个临时服务器事务（叫做一个活动）开始。然后客户端在每个希望修改的VR上执行一个<literal>CHECKOUT</literal>操作，这在活动里创建了一些临时<quote>工作资源</quote>，然后可以使用<literal>PUT</literal>和<literal>PROPPATCH</literal>方法修改。最后，客户端对每个工作资源执行一个<literal>CHECKIN</literal>，在每个VCR创建了一个VR，并且整个活动会被删除。
+ <para>一些DeltaV服务器也支持客户端可以有完全特定私有工作拷贝的思想，当客户端希望提交修改到服务器，它通过使用<literal>MKACTIVITY</literal>方法创建一个临时服务器事务（叫做一个<firstterm>活动</firstterm>）开始。然后客户端在每个希望修改和发送<literal>PUT</literal>请求的资源上执行一个<literal>CHECKOUT</literal>操作，最后，客户端对每个工作资源执行一个<literal>CHECKIN</literal>，在每个VCR创建了一个VR，并且整个活动会被删除。
</para>
</listitem>
</varlistentry>
@@ -105,7 +129,7 @@
<varlistentry>
<term>配置</term>
<listitem>
- <para>DeltaV允许你定义叫做<quote>配置</quote>的灵活的VCR集合，不需要对应特定的目录，每个VCR的内容可以使用<literal>UPDATE</literal>方法指向特定的VR。一旦配置是理想的，客户端可以创建一个整个配置的<quote>快照</quote>，叫做<quote>基线</quote>。客户端使用<literal>CHECKOUT</literal>和<literal>CHECKIN</literal>方法捕捉特定的配置状态，很像它们使用这些方法创建VCR的特定VR状态。
+ <para>DeltaV允许你定义叫做<quote>配置</quote>的灵活的资源集合，不需要对应特定的目录。一个配置可以指向特定的文件的版本，然后可以做<quote>基线</quote>快照，这很像标签。
</para>
</listitem>
</varlistentry>
@@ -113,242 +137,561 @@
<varlistentry>
<term>扩展性</term>
<listitem>
- <para>DeltaV定义了新方法<literal>REPORT</literal>，允许客户端和服务器执行自定义的数据交换。客户端发送一个带有包含自定义数据的完全标记的XML主体的<literal>REPORT</literal>请求；假定服务器理解特定的报告类型，它使用一个等同的XML主体来响应，这个技术与XML-RPC很类似。
+ <para>DeltaV定义了新方法<literal>REPORT</literal>，允许客户端和服务器执行自定义的数据交换。尽管DeltaV定义了一系列客户端可以请求的标准历史报告，服务器也可以自由定义报告。客户端发送一个带有包含自定义数据的完全标记的XML主体的<literal>REPORT</literal>请求；假定服务器理解特定的报告类型，它使用一个等同的XML主体来响应，这个技术与XML-RPC很类似。
</para>
</listitem>
</varlistentry>
-
- <varlistentry>
- <term>自动版本化</term>
- <listitem>
- <para>对大多数，这是DeltaV的<quote>杀手</quote>特性，如果DeltaV服务器支持这个特性，然后基本的WebDAV客户端（例如，那些不知道版本化的客户端）仍然可以对服务器进行写操作，服务器可以悄无声息的执行版本操作。在最简单的例子里，一个从基本的WebDAV客户端发送的无知的<literal>PUT</literal>可能会被服务器转化为<literal>CHECKOUT</literal>、<literal>PUT</literal>、<literal>CHECKIN</literal>。
- </para>
- </listitem>
- </varlistentry>
-
+
</variablelist>
</sect2>
</sect1>
- <sect1 id="svn-ap-c-sect-2">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.webdav.svn-and-deltav">
<title>Subversion和DeltaV</title>
- <para>所以Subversion与其他DeltaV的兼容性如何？两个字：不好，至少在Subversion 1.0还不好。
- </para>
- <para>当libsvn_ra_dav发送DeltaV到服务器，Subversion客户端<emphasis>不是</emphasis>一个普通目的的DeltaV客户端。实际上，它希望服务器一些自定义的特性（特别是通过自定义的<literal>REPORT</literal>请求）。更进一步，mod_dav_svn<emphasis>不是</emphasis>一个普通目的的DeltaV服务器，它只实现了DeltaV的一个严格子集，一个更加普通的WebDAV或DeltaV客户端可能与之很好的交互工作，但是只有在服务器非常窄的已经实现的特性范围之内。Subversion开发团队计划会设法在以后的版本中完成普通的WebDAV交互性。
- </para>
-
- <sect2 id="svn-ap-c-sect-2.1">
- <title>影射Subversion到DeltaV</title>
-
- <para>这里是多种Subversion客户端如何使用DeltaV操作的一个非常<quote>高级别</quote>描述。在很多种情况下，这些解释过于粗略，这<emphasis>不</emphasis>能作为阅读Subversion源代码和与开发者交谈的替代。
- </para>
-
- <variablelist>
-
- <varlistentry>
- <term>svn checkout/list</term>
- <listitem>
- <para>对集合执行一个深度为1的<literal>PROPFIND</literal>来得到直接孩子的列表，对每个孩子执行一个<literal>GET</literal>（也可能是一个<literal>PROPFIND</literal>），递归到集合并且重复。
- </para>
- </listitem>
- </varlistentry>
+ <para>The original WebDAV standard has been widely successful.
+ Every modern computer operating system has a general WebDAV
+ client built-in (details to follow), and a number of popular
+ standalone applications are also able to speak WebDAV —
+ Microsoft Office, Dreamweaver, and Photoshop to name a few. On
+ the server end, the Apache webserver has been able to provide
+ WebDAV services since 1998 and is considered the de-facto
+ open-source standard. There are several other commercial WebDAV
+ servers available, including Microsoft's own IIS.</para>
+
+ <para>DeltaV, unfortunately, has not been so successful. It's
+ very difficult to find any DeltaV clients or servers. The few
+ that do exist are relatively unknown commercial products, and
+ thus it's very difficult to test interoperability. It's not
+ entirely clear as to why DeltaV has remained stagnant. Some
+ argue that the specification is just too complex, others argue
+ that while WebDAV's features have mass appeal (even the least
+ technical users appreciate network file-sharing), version
+ control features aren't interesting or necessary for most users.
+ Finally, some have argued that DeltaV remains unpopular because
+ there's still no open-source server product which implements
+ it.</para>
+
+ <para>When Subversion was still in its design phase, it seemed
+ like a great idea to use Apache httpd as the main network
+ server. It already had a module to provide WebDAV services.
+ DeltaV was a relatively new specification. The hope was that
+ the Subversion server module (mod_dav_svn) would eventually
+ evolve into an open-source DeltaV reference implementation.
+ Unfortunately, DeltaV has a very specific versioning model that
+ doesn't quite line up with Subversion's model. Some concepts
+ were mappable, others were not.</para>
+
+ <para>The upshot is that</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>The Subversion client is not a fully-implemented DeltaV
+ client.</para>
- <varlistentry>
- <term>svn commit</term>
- <listitem>
- <para>
- 使用<literal>MKACTIVITY</literal>创建一个活动，然后对每个修改项目执行一个<literal>CHECKOUT</literal>，紧跟一个对新数据的<literal>PUT</literal>。最终，一个<literal>MERGE</literal>请求导致一个隐含的对所有工作资源的<literal>CHECKIN</literal>。
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>svn update/switch/status/merge/diff</term>
- <listitem>
- <para>
- 发送一个自定义的描述工作拷贝混合修订版本（和混合URL）状态的<literal>REPORT</literal>请求，服务器发送一个描述需要更新的项目和文件内容增量数据的响应。解析响应，对于update和switch，在工作拷贝安装新数据，对于diff和merge，与工作拷贝的数据比较，应用修改作为本地修改。
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </sect2>
-
- <sect2 id="svn-ap-c-sect-2.2">
- <title>自动版本化支持</title>
-
- <para>在写作的时候，有一个事实就是这个世界只有很少的DeltaV客户端；RFC 3253一直是相对比较新。然而用户有一些<quote>普通的</quote>客户端，因为几乎所有的现代操作系统现在拥有集成的基本WebDAV客户端，因为这一点，Subversion开发者认识到如果Subversion 1.0可以支持DeltaV自动版本化这一交互特性会是最好的方法。
- </para>
-
- <para>为了激活mod_dav_svn的自动版本化，使用<filename>httpd.conf</filename> <literal>Location</literal>区块的<literal>SVNAutoversioning</literal>指示，例如：
- </para>
-
- <screen>
-<Location /repos>
- DAV svn
- SVNPath /absolute/path/to/repository
- SVNAutoversioning on
-</Location>
-</screen>
-
- <para>通常情况下，如果一个原始的WebDAV客户端尝试<literal>PUT</literal>到你的版本库位置的一个路径，mod_dav_svn会直接拒绝这个请求。（通常只允许对于DeltaV<quote>活动</quote>里面的对于<quote>工作资源</quote>的操作。）通过打开<literal>SVNAutoversioning</literal>，无论何时，服务器会把<literal>PUT</literal>请求转化为内部的<literal>MKACTIVITY</literal>、<literal>CHECKOUT</literal>、<literal>PUT</literal>和<literal>CHECKIN</literal>。一个普通的日志信息是自动生成的，并且创建一个新的文件系统修订版本。
- </para>
-
- <para>因为有这样多的操作系统已经集成了WebDAV能力，这个特性的用例近似于空想：想象一个普通用户运行Microsoft Windows或Mac OS的办公室，每个电脑<quote>装配</quote>了一个Subversion版本库，作为一个普通的网络共享。他们向普通目录一样操作服务器：从服务器打开文件，修改并且保存回服务器。但在这个幻想中，服务器自动版本化所有的事情，之后，一个系统管理员可以使用Subversion客户端来查找和检索所有旧的版本。
- </para>
-
- <para>这个幻想是现实吗？完全不是，主要的障碍是Subversion 1.0不支持WebDAV的<literal>LOCK</literal>方法<literal>UNLOCK</literal>，大多数操作系统的DAV客户端尝试<literal>LOCK</literal>一个直接从DAV装配的网络共享的资源，到目前为止，用户必须要把文件从DAV共享拷贝到本地磁盘，编辑文件，然后再拷贝回去。没有理想的自动版本化，但还是可行的。
- </para>
-
- </sect2>
-
- <sect2 id="svn-ap-c-sect-2.3">
- <title>选择mod_dav_lock</title>
+ <para>The client needs certain things from the server that
+ DeltaV cannot provide, and thus is largely dependent on a
+ number of Subversion-specific <literal>REPORT</literal>
+ requests that only mod_dav_svn understands.</para>
+ </listitem>
+
+ <listitem>
+ <para>mod_dav_svn is not a fully-implemented DeltaV server.</para>
+
+ <para>Many portions of the DeltaV specification were irrelevant to
+ Subversion, and thus left unimplemented.</para>
+ </listitem>
- <para>Apache模块mod_dav是一个复杂的野兽：它理解和解析所有的WebDAV和DeltaV方法，然而它依赖于后端<quote>提供者</quote>来访问资源本身。
- </para>
-
- <para>在最简单的化身里，一个用户可以使用mod_dav_fs可以作为mod_dav的提供者，mod_dav_fs使用普通的文件系统来存放文件和目录，只理解平凡的WebDAV方法，不是DeltaV。
- </para>
+ </orderedlist>
- <para>在另一方面，Subversion使用mod_dav_svn作为mod_dav的提供者，mod_dav_svn理解除了<literal>LOCK</literal>以外的所有WebDAV方法，并且理解相当大的DeltaV方法子集，它访问Subversion版本库的数据，而不是真实的文件系统。Subversion 1.0不支持锁定，因为这会非常难于实现，因为Subversion使用拷贝-修改-合并模型。<footnote><para>Subversion可能有一天会开发一个保留检出的锁定模型，可以与拷贝-修改-合并和平相处，但是可能不会立刻发生。
- </para></footnote></para>
-
- <para>在Apache httpd-2.0里，mod_dav可以通过追踪私有数据库的锁来支持<literal>LOCK</literal>方法，假定提供者会乐于接受这一点。在Apache httpd-2.1或以后的版本，这个锁定支持会拆到一个独立的模块，mod_dav_lock。它允许任何mod_dav提供者利用锁数据库的好处，包括mod_dav_svn，即使mod_dav_svn实际上不理解锁定。
- </para>
+ <para>There is still some debate in the developer community as to
+ whether or not it's worthwhile to remedy either of these
+ situations. It's fairly unrealistic to change Subversion's
+ design to match DeltaV, so there's probably no way the client
+ can ever learn to get everything it needs from a general DeltaV
+ server. On the other hand,
+ mod_dav_svn <emphasis>could</emphasis> be further developed to
+ implement all of DeltaV, but it's hard to find motivation to do
+ so—there are almost no DeltaV clients to interoperate
+ with.</para>
- <para>感到困惑？</para>
+ </sect1>
- <para>简言之，你可以使用Apache
- httpd-2.1（或更晚的）的mod_dav_lock来创建一个错觉，也就是mod_dav_svn负责了<literal>LOCK</literal>操作。确定mod_dav_lock已经编译到httpd或已经在<filename>httpd.conf</filename>中加载，然后只需要在<literal>Location</literal>简单的添加如下的<literal>DAVGenericLockDB</literal>指示：
- </para>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.webdav.autoversioning">
+ <title>Autoversioning</title>
+
+ <para>While the Subversion client is not a full DeltaV client, nor
+ the Subversion server a full DeltaV server, there's still a
+ glimmer of WebDAV interoperability to be happy about: it's
+ called autoversioning.</para>
+
+ <para>Autoversioning is an optional feature defined in the DeltaV
+ standard. A typical DeltaV server will reject an ignorant
+ WebDAV client attempting to do a <literal>PUT</literal> to a
+ file that's under version control. To change a
+ version-controlled file, the server expects a series proper
+ versioning requests: something like
+ <literal>MKACTIVITY</literal>, <literal>CHECKOUT</literal>,
+ <literal>PUT</literal>, <literal>CHECKIN</literal>. But if the
+ DeltaV server supports autoversioning, then write-requests from
+ basic WebDAV clients are accepted. The server behaves *as if*
+ the client had issued the proper series of versioning requests,
+ performing a commit under the hood. In other words, it allows a
+ DeltaV server to interoperate with ordinary WebDAV
+ clients.</para>
+
+ <para>Because so many operating systems already have integrated
+ WebDAV clients, the use case for this feature borders on
+ fantastical: imagine an office of ordinary users running
+ Microsoft Windows or Mac OS. Each user <quote>mounts</quote>
+ the Subversion repository, which appears to be an ordinary
+ network folder. They use the shared folder as they always do:
+ open files, edit them, save them. Meanwhile, the server is
+ automatically versioning everything. Any administrator (or
+ knowledgeable user) can still use a Subversion client to search
+ history and retrieve older versions of data.</para>
+
+ <para>This scenario isn't fiction: it's real and it works, as of
+ Subversion 1.2 and later. To activate autoversioning in
+ mod_dav_svn, use the <literal>SVNAutoversioning</literal>
+ directive within the <filename>httpd.conf</filename> Location
+ block, like so:</para>
- <screen>
+ <screen>
<Location /repos>
DAV svn
- SVNPath /absolute/path/to/repository
+ SVNPath /path/to/repository
SVNAutoversioning on
- DavGenericLockDB /path/to/store/locks
</Location>
</screen>
- <para>这个技术是一个有危险的业务；在一些情况，mod_dav_svn现在已经接近WebDAV客户端，它宣称接受<literal>LOCK</literal>请求，但是实际上锁并不是在所有的级别上强制执行。如果第二个WebDAV客户端尝试<literal>LOCK</literal>锁住同样的资源，然后mod_dav_lock会注意到并且正确的拒绝这个请求，但是完全没有办法来防止一个普通的Subversion客户端使用<command>svn commit</command>来修改文件！如果你使用这个技术，你给用户权利来践踏其他人的修改，更具体一点，一个WebDAV客户端会不小心覆盖普通Subversion客户端提交的修改。
- </para>
-
- <para>在另一方面，如果你小心设置你的环境变量，你会减轻这个风险，例如，如果<emphasis>所有</emphasis>用户使用WebDAV客户端（而不是Subversion客户端），然后事情变得美好了。
- </para>
+ <para>When SVNAutoversioning is active, write requests from WebDAV
+ clients result in automatic commits. A generic log message is
+ auto-generated and attached to each revision.</para>
+
+ <para>Before activating this feature, however, understand what
+ you're getting into. WebDAV clients tend to do
+ <emphasis>many</emphasis> write requests, resulting in a huge
+ number of automatically committed revisions. For example, when
+ saving data, many clients will do a <literal>PUT</literal> of a
+ 0-byte file (as a way of reserving a name) followed by another
+ <literal>PUT</literal> with the real filedata. The single
+ file-write results in two separate commits. Also consider that
+ many applications auto-save every few minutes, resulting in even
+ more commits.</para>
+
+ <para>If you have a post-commit hook program that sends email, for
+ example, you may want to disable email generation either
+ altogether, or on certain sections of the repository; it depends
+ on whether you think the influx of emails will still prove to be
+ valuable notifications or not. Also, a smart post-commit hook
+ program can distinguish between a transaction created via
+ autoversioning and one created through a normal <command>svn
+ commit</command>. The trick is to look for a revision property
+ named <literal>svn:autoversioned</literal>. If present, the
+ commit was made by a generic WebDAV client.</para>
- </sect2>
-
</sect1>
-
- <sect1 id="svn-ap-c-sect-3">
- <title>自动版本化交互性</title>
-
- <para>在这个小节，我们会描述最普通的原始WebDAV客户端（写作的时刻），和它们是如何与使用<literal>SVNAutoversioning</literal>指示的mod_dav_svn服务器的运作。RFC 2518是一个有点大，并且有一点太灵活。每个WebDAV客户端的行为都有些许区别，并且产生许多不同的小问题。
- </para>
-
- <!-- list of subsections goes here. -->
-
- <sect2 id="svn-ap-c-sect-3.1">
- <title>Win32网络文件夹</title>
-
- <para>Windows 98、2000和XP有一个集成的WebDAV客户端叫做<quote>网络文件夹</quote>，在Windows 98，这个特性需要明确安装；如果提供，一个<quote>网络文件夹</quote>就会出现在我的电脑，在Windows 2000和XP，只需要简单得打开我的网络位置，运行添加网络位置图标。当出现提示，输入一个WebDAV的URL，我的网络位置中就会出现一个共享文件夹。
- </para>
- <para>大多数写操作对于自动版本化的mod_dav_svn服务器工作正常，但是有一些问题：
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>如果一个Windows XP电脑是一个NT域的成员，它看起来不能连接到WebDAV共享，重复提示要输入用户名和密码，即使Apache服务器没有要求进行认证！如果这个机器不是NT域的一部分，这个共享可以成功装载。
- </para>
-
- <para>这个问题源于Windows XP创建网络文件夹快捷方式（<filename>.lnk</filename>文件）的方法的bug。它有时候会使用<quote>UNC</quote> （Universal Naming Convention） 路径来代替WebDAV共享URL，这导致资源管理器尝试使用SMB而不是HTTP来进行连接。
- </para>
-
- <para>这个问题的解决方法是在Windows 2000创建<filename>.lnk</filename>快捷方式，然后拷贝到Windows XP电脑，如果有人可以逆转<filename>.lnk</filename>文件的格式，也可以使用十六进制编辑器来<quote>修正</quote>快捷方式。
- </para>
- </listitem>
-
- <listitem>
- <para>一个文件不可以直接在共享中打开编辑；它可能一直是只读的。mod_dav_lock技术也无能为力，因为网络文件夹根本不使用<literal>LOCK</literal>方法，前面提到的<quote>拷贝、编辑和再拷贝</quote>根本不工作。在共享中的文件可以成功的被本地修改的拷贝覆盖。
- </para>
- </listitem>
-
- </itemizedlist>
-
- </sect2>
-
- <sect2 id="svn-ap-c-sect-3.2">
- <title>Mac OS X</title>
-
- <para>Apple的OS X操作系统也集成了WebDAV客户端，从Finder选择Go菜单的<quote>Connect to
- Server</quote>，输入一个WebDAV的URL，它会作为一个磁盘在桌面出现，就像任何文件服务器。<footnote><para>Unix用户也可以运行<command>mount
- -t webdav URL /mountpoint</command>。
- </para></footnote></para>
-
- <para>很不幸，客户端拒绝与一个自动版本化的mod_dav_svn工作，因为它缺乏<literal>LOCK</literal>支持，Mac OS X在初始化HTTP的<literal>OPTIONS</literal>特性交换时会发现缺失了<literal>LOCK</literal>能力，因而决定以只读方式装配Subversion版本库，之后，不可以进行写操作。为了将版本库按照读写方式装配，你<emphasis>必须</emphasis>使用前面讨论的mod_dav_lock技巧。一旦锁定看起来工作了，共享会运作良好：文件可以直接以读/写模式打开，尽管每次存储操作会导致客户端对临时位置执行一个<literal>PUT</literal>，对原文件的<literal>DELETE</literal>操作和把临时资源<literal>MOVE</literal>到原文件。每次存盘会产生三个新的Subversion修订版本！
- </para>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.webdav.clients">
+ <title>Client Interoperability</title>
+
+ <para>All WebDAV clients fall into one of three
+ categories—standalone applications, file-explorer
+ extensions, or filesystem implementations. These categories
+ broadly define the types of WebDAV functionality available to
+ users. <xref linkend="svn.webdav.clients.tbl-1"/> gives our
+ categorization and a quick description of some common pieces of
+ WebDAV-enabled software. More details about these software
+ offerings, as well as their general category, can be found in
+ the sections that follow.</para>
+
+ <table id="svn.webdav.clients.tbl-1">
+ <title>Common WebDAV Clients</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Software</entry>
+ <entry>Category</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Adobe Photoshop</entry>
+ <entry>Standalone WebDAV applications</entry>
+ <entry>Image editing software, allowing direct opening
+ from, and writing to, WebDAV URLs</entry>
+ </row>
+ <row>
+ <entry>Cadaver</entry>
+ <entry>Standalone WebDAV applications</entry>
+ <entry>Command-line WebDAV client supporting file
+ transfer, tree, and locking operations</entry>
+ </row>
+ <row>
+ <entry>DAV Explorer</entry>
+ <entry>Standalone WebDAV applications</entry>
+ <entry>GUI tool for exploring WebDAV shares</entry>
+ </row>
+ <row>
+ <entry>davfs2</entry>
+ <entry>WebDAV filesystem implementation</entry>
+ <entry>Linux file system driver that allows you to mount a
+ WebDAV share</entry>
+ </row>
+ <row>
+ <entry>GNOME Nautilus</entry>
+ <entry>File-explorer WebDAV extensions</entry>
+ <entry>GUI file explorer able to perform tree
+ operations on a WebDAV share</entry>
+ </row>
+ <row>
+ <entry>KDE Konqueror</entry>
+ <entry>File-explorer WebDAV extensions</entry>
+ <entry>GUI file explorer able to perform tree
+ operations on a WebDAV share</entry>
+ </row>
+ <row>
+ <entry>Mac OS X</entry>
+ <entry>WebDAV filesystem implementation</entry>
+ <entry>Operating system with built-in support for mounting
+ WebDAV shares locally</entry>
+ </row>
+ <row>
+ <entry>Macromedia Dreamweaver</entry>
+ <entry>Standalone WebDAV applications</entry>
+ <entry>Web production software able to directly read from
+ and write to WebDAV URLs</entry>
+ </row>
+ <row>
+ <entry>Microsoft Office</entry>
+ <entry>Standalone WebDAV applications</entry>
+ <entry>Office productivity suite with several components
+ able to directly read from and write to WebDAV
+ URLs</entry>
+ </row>
+ <row>
+ <entry>Microsoft Webfolders</entry>
+ <entry>File-explorer WebDAV extensions</entry>
+ <entry>GUI file explorer program able to perform tree
+ operations on a WebDAV share</entry>
+ </row>
+ <row>
+ <entry>Novell NetDrive</entry>
+ <entry>WebDAV filesystem implementation</entry>
+ <entry>Drive-mapping program for assigning Windows drive
+ letters to a mounted remote WebDAV share</entry>
+ </row>
+ <row>
+ <entry>SRT WebDrive</entry>
+ <entry>WebDAV filesystem implementation</entry>
+ <entry>File transfer software which, among other things,
+ allows the assignment of Windows drive letters to a
+ mounted remote WebDAV share</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.webdav.clients.standalone">
+ <title>Standalone WebDAV applications</title>
+
+ <para>A WebDAV application is a program which contains built-in
+ functionality for speaking WebDAV protocols with a WebDAV
+ server. We'll cover some of the most popular programs with
+ this kind of WebDAV support.</para>
- <para>还要警告一点：OS X的WebDAV客户端可以对HTTP重定向完全敏感，如果你不能装配版本库，你可以在<filename>httpd.conf</filename>开启<literal>BrowserMatch</literal>指示：
- </para>
+ <sect3 id="svn.webdav.clients.standalone.windows">
+ <title>Microsoft Office, Dreamweaver, Photoshop</title>
+
+ <para>On Windows, there are several well-known applications
+ that contain integrated WebDAV client functionality, such as
+ Microsoft's Office,
+ <footnote>
+ <para>WebDAV support was removed from Microsoft Access for
+ some reason, but exists in the rest of the Office
+ suite.</para>
+ </footnote>
+ Adobe's Photoshop, and Macromedia's Dreamweaver programs.
+ They're able to directly open and save to URLs, and tend to
+ make heavy use of WebDAV locks when editing a file.</para>
+
+ <para>Note that while many of these programs also exist for
+ the Mac OS X, they do not appear to support WebDAV directly
+ on that platform. In fact, on Mac OS X, the
+ <guimenu>File->Open</guimenu> dialog box doesn't allow
+ one to type a path or URL at all. It's likely that the
+ WebDAV features were deliberately left out of Macintosh
+ versions of these programs, since OS X already provides such
+ excellent low-level filesystem support for WebDAV.</para>
+
+ </sect3>
- <screen>
-BrowserMatch "^WebDAVFS/1.[012]" redirect-carefully
+ <sect3 id="svn.webdav.clients.standalone.free">
+ <title>Cadaver, DAV Explorer</title>
+
+ <para>Cadaver is a bare-bones Unix commandline program for
+ browsing and changing WebDAV shares. Like the Subversion
+ client, it uses the neon HTTP library—not surprisingly,
+ both neon and cadaver are written by the same author. Cadaver
+ is free software (GPL license) and is available at <ulink
+ url="http://www.webdav.org/cadaver/"/>.</para>
+
+ <para>Using cadaver is similar to using a commandline FTP
+ program, and thus it's extremely useful for basic WebDAV
+ debugging. It can be used to upload or download files in a
+ pinch, and also to examine properties, copy, move, lock or
+ unlock files:</para>
+
+ <screen>
+$ cadaver http://host/repos
+dav:/repos/> ls
+Listing collection `/repos/': succeeded.
+Coll: > foobar 0 May 10 16:19
+ > playwright.el 2864 May 4 16:18
+ > proofbypoem.txt 1461 May 5 15:09
+ > westcoast.jpg 66737 May 5 15:09
+
+dav:/repos/> put README
+Uploading README to `/repos/README':
+Progress: [=============================>] 100.0% of 357 bytes succeeded.
+
+dav:/repos/> get proofbypoem.txt
+Downloading `/repos/proofbypoem.txt' to proofbypoem.txt:
+Progress: [=============================>] 100.0% of 1461 bytes succeeded.
</screen>
+ <para>DAV Explorer is another standalone WebDAV client, written
+ in Java. It's under a free Apache-like license and is
+ available at <ulink url="http://www.ics.uci.edu/~webdav/"/>.
+ DAV Explorer does everything cadaver does, but has the
+ advantages of being portable and being more user-friendly GUI
+ application. It's also one of the first clients to support
+ the new WebDAV Access Control Protocol (RFC 3744).</para>
+
+ <para>Of course, DAV Explorer's ACL support is useless in this
+ case, since mod_dav_svn doesn't support it. The fact that
+ both Cadaver and DAV Explorer support some limited DeltaV
+ commands isn't particularly useful either, since they don't
+ allow <literal>MKACTIVITY</literal> requests. But it's not
+ relevant anyway; we're assuming all of these clients are
+ operating against an autoversioning repository.</para>
+
+ </sect3>
</sect2>
- <sect2 id="svn-ap-c-sect-3.3">
- <title>Unix: Nautilus 2</title>
-
- <para>Nautilus是GNOME桌面的官方文件管理器/浏览器，它的主页在<systemitem
- class="url">http://www.gnome.org/projects/nautilus/</systemitem>，只需要在Nautilus窗口中输入一个WebDAV的URL，DAV共享就会像本地磁盘一样出现。
- </para>
+ <!-- =============================================================== -->
+ <sect2 id="svn.webdav.clients.file-explorer-extensions">
+ <title>File-explorer WebDAV extensions</title>
+
+ <para>Some popular file explorer GUI programs support WebDAV
+ extensions which allow a user to browse a DAV share as if it
+ was just another directory on the local computer, and allowing
+ basic tree editing operations on the items in that share. For
+ example, Windows Explorer is able to browse a WebDAV server as
+ a <quote>network place</quote>. Users can drag files to and
+ from the desktop, or can rename, copy, or delete files in the
+ usual way. But because it's only a feature of the
+ file-explorer, the DAV share isn't visible to ordinary
+ applications. All DAV interaction must happen through the
+ explorer interface.</para>
- <para>通常情况下，Nautilus 2与自动版本化的mod_dav_svn一起工作相当的好，只是有下面一些警告：
- </para>
+ <sect3 id="svn.webdav.clients.file-explorer-extensions.windows">
+ <title>Microsoft Webfolders</title>
+
+ <para>Microsoft was one of the original backers of the WebDAV
+ specification, and first started shipping a client in Windows
+ 98, known as <quote>Webfolders</quote>. This client was also
+ shipped in Windows NT4 and 2000.</para>
+
+ <para>The original Webfolders client was an extension to
+ Explorer, the main GUI program used to browse filesystems. It
+ works well enough. In Windows 98, the feature might need to
+ be explicitly installed if Webfolders aren't already visible
+ inside <quote>My Computer</quote>. In Windows 2000, simply
+ add a new <quote>network place</quote>, enter the URL, and the
+ WebDAV share will pop up for browsing.</para>
+
+ <para>With the release of Windows XP, Microsoft started shipping
+ a new implementation of Webfolders, known as the <quote>WebDAV
+ mini-redirector</quote>. The new implementation is a
+ filesystem-level client, allowing WebDAV shares to be mounted
+ as drive letters. Unfortunately, this implementation is
+ incredibly buggy. The client usually tries to convert http
+ URLs (<literal>http://host/repos</literal>) into UNC share
+ notation (<literal>\\host\repos</literal>); it also often
+ tries to use Windows Domain authentication to respond to
+ basic-auth HTTP challenges, sending usernames as
+ <literal>HOST\username</literal>. These interoperability
+ problems are severe and documented in numerous places around
+ the web, to the frustration of many users. Even Greg Stein,
+ the original author of Apache's WebDAV module, recommends
+ against trying to use XP Webfolders against an Apache
+ server.</para>
+
+ <para>It turns out that the original
+ <quote>Explorer-only</quote> Webfolders implementation isn't
+ dead in XP, it's just buried. It's still possible to find it
+ by using this technique:</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>Go to 'Network Places'.</para>
+ </listitem>
+
+ <listitem>
+ <para>Add a new network place.</para>
+ </listitem>
+
+ <listitem>
+ <para>When prompted, enter the URL of the repository, but
+ <emphasis>include a port number</emphasis> in the URL.
+ For example, <literal>http://host/repos</literal> would be
+ entered as <literal>http://host:80/repos</literal> instead.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Respond to any authentication prompts.</para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>There are a number of other rumored workarounds to the
+ problems, but none of them seem to work on all versions and
+ patchlevels of Windows XP. In our tests, only the previous
+ algorithm seems to work consistently on every system. The
+ general consensus of the WebDAV community is that you should
+ avoid the new Webfolders implementation and use the old one
+ instead, and that if you need real a real filesystem-level
+ client for Windows XP, then use a third-party program like
+ WebDrive or NetDrive.</para>
- <itemizedlist>
+ </sect3>
- <listitem>
- <para>任何在共享里直接打开的文件是只读的，即使mod_dav_lock的技巧也看起来无效。Nautilus看起来从没有关注过<literal>LOCK</literal>方法，<quote>本地拷贝、编辑和拷贝回去</quote>的技巧还可以工作，但是很不幸，Nautilus的覆盖旧文件是通过首先<literal>DELETE</literal>进行的，这创建了一个额外的修订版本。
- </para>
- </listitem>
-
- <listitem>
- <para>当覆盖或创建一个文件，Nautilus首先<literal>PUT</literal>一个空文件，然后使用第二个<literal>PUT</literal>覆盖它，这创建了两个Subversion文件系统修订版本，而不是一个。
- </para>
- </listitem>
-
- <listitem>
- <para>当删除了一个集合，它对每个独立的孩子而不是集合本身发出HTTP的<literal>DELETE</literal>操作，这会创建一系列新的修订版本。
- </para>
- </listitem>
+ <sect3 id="svn.webdav.clients.file-explorer-extensions.linux-de">
+ <title>Nautilus, Konqueror</title>
+
+ <para>Nautilus is the official file manager/browser for the
+ GNOME desktop (<ulink url="http://www.gnome.org"/>), and
+ Konqueror is the manager/browser for KDE desktop (<ulink
+ url="http://www.kde.org"/>). Both of these applications have
+ an explorer-level WebDAV client built-in, and operate just
+ fine against an autoversioning repository.</para>
+
+ <para>In GNOME's Nautilus, from the <guimenu>File
+ menu</guimenu>, select <guimenuitem>Open
+ location</guimenuitem> and enter the URL. The repository
+ should then be displayed like any other filesystem.</para>
+
+ <para>In KDE's Konqueror, you need to use the
+ <literal>webdav://</literal> scheme when entering the URL in
+ the location bar. If you enter an <literal>http://</literal>
+ URL, Konqueror will behave like an ordinary web browser.
+ You'll likely see the generic HTML directory listing produced
+ by mod_dav_svn. By entering
+ <literal>webdav://host/repos</literal> instead of
+ <literal>http://host/repos</literal>, Konqueror becomes a
+ WebDAV client and displays the repository as a
+ filesystem.</para>
+
+ </sect3>
+ </sect2>
- </itemizedlist>
+ <sect2 id="svn.webdav.clients.fs-impl">
+ <title>WebDAV filesystem implementation</title>
- </sect2>
+ <para>The WebDAV filesystem implementation is arguably the best
+ sort of WebDAV client. It's implemented as a low-level
+ filesystem module, typically within the operating system's
+ kernel. This means that the DAV share is mounted like any
+ other network filesystem, similar to mounting an NFS share on
+ Unix, or attaching an SMB share as drive-letter in Windows.
+ As a result, this sort of client provides completely
+ transparent read/write WebDAV access to all programs.
+ Applications aren't even aware that WebDAV requests are
+ happening.</para>
- <sect2 id="svn-ap-c-sect-3.4">
- <title>Linux davfs2</title>
+ <sect3 id="svn.webdav.clients.fs-impl.windows">
+ <title>WebDrive, NetDrive</title>
+
+ <para>Both WebDrive and NetDrive are excellent commercial
+ products which allows a WebDAV share to be attached as drive
+ letters in Windows. We've had nothing but success with
+ these products. At the time of writing, WebDrive can be
+ purchased from South River Technologies (<ulink
+ url="http://www.southrivertech.com"/>). NetDrive ships with
+ Netware, is free of charge, and can be found by searching
+ the web for <quote>netdrive.exe</quote>. Though it is
+ freely available online, users are required to have a
+ Netware license. (If any of that sounds odd to you, you're
+ not alone. See this page on Novell's website: <ulink
+ url="http://www.novell.com/coolsolutions/qna/999.html"/>)</para>
+
+ </sect3>
- <para>Linux davfs2是一个Linux内核的文件系统模块，它的开发位于<systemitem
- class="url">http://dav.sourceforge.net/</systemitem>。一旦安装，一个WebDAV网络共享可以使用普通的Linux的<command>mount</command>命令装配。
- </para>
+ <sect3 id="svn.webdav.clients.fs-impl.macosx">
+ <title>Mac OS X</title>
- <para>一个公开的秘密就是DAV客户端不会与mod_dav_svn的自动版本化完全工作正常，即使一个单独对服务器的写尝试需要<literal>LOCK</literal>请求作为前提，而这是mod_dav_svn不支持的。此时，还没有数据表明是否可以使用mod_dav_lock解决这个问题。
- </para>
+ <para>Apple's OS X operating system has an integrated
+ filesystem-level WebDAV client. From the Finder, select the
+ <guimenuitem>Connect to Server</guimenuitem> item from the
+ <guimenu>Go menu</guimenu>. Enter a WebDAV URL, and it
+ appears as a disk on the desktop, just like any other mounted
+ volume.<footnote><para>From the Darwin terminal, one can also
+ run <literal>mount -t webdav URL
+ /mountpoint</literal></para></footnote>.</para>
+
+ <para>Note that if your mod_dav_svn is older than version 1.2,
+ OS X will refuse to mount the share as read-write; it will
+ appear as read-only. This is because the OS X insists on
+ locking support for read-write shares, and the ability to lock
+ files first appeared in Subversion 1.2.</para>
+
+ <para>One more word of warning: OS X's WebDAV client can
+ sometimes be overly sensitive to HTTP redirects. If OS X is
+ unable to mount the repository at all, you may need to enable
+ the BrowserMatch directive in the Apache server's
+ <filename>httpd.conf</filename>:</para>
+
+ <screen>
+BrowserMatch "^WebDAVFS/1.[012]" redirect-carefully
+</screen>
+
+ </sect3>
+ <sect3 id="svn.webdav.clients.fs-impl.linux">
+ <title>Linux davfs2</title>
+
+ <para>Linux davfs2 is a filesystem module for the Linux kernel,
+ whose development is located at <ulink
+ url="http://dav.sourceforge.net/"/>. Once installed, a WebDAV
+ network share can be mounted with the usual Linux mount
+ command:</para>
+
+ <screen>
+$ mount.davfs http://host/repos /mnt/dav
+</screen>
+
+ </sect3>
</sect2>
-
</sect1>
</appendix>
@@ -358,3 +701,4 @@
sgml-parent-document: ("book.xml" "appendix")
end:
-->
+
Copied: trunk/src/zh/book/appc.xml (from r1856, /trunk/src/zh/book/appd.xml)
==============================================================================
--- /trunk/src/zh/book/appd.xml (original)
+++ trunk/src/zh/book/appc.xml Wed Jan 25 01:01:34 2006
@@ -1,14 +1,11 @@
-<appendix id="svn-ap-d">
+<appendix id="svn.3rdparty">
<title>第三方工具</title>
<simplesect>
<para>Subversion的模块设计（在<xref
- linkend="svn-ch-8-sect-1"/>讨论过）和语言绑定的能力（在<xref linkend="svn-ch-8-sect-2.3"/>描述过）使的我们可以作为扩展和后端支持来替代软件的某些部分，在这个附录里，我们会简略介绍一些使用Subversion功能的第三方的工具。
- </para>
-
- <para>关于更新的信息，可以在Subversion的网站（<systemitem
- class="url">http://subversion.tigris.org/project_links.html</systemitem>）查看。
+ linkend="svn.developer.layerlib"/>讨论过）和语言绑定的能力（在<xref linkend="svn.developer.usingapi.otherlangs"/>描述过）使的我们可以作为扩展和后端支持来替代软件的某些部分，在这个附录里，我们会简略介绍一些使用Subversion功能的第三方的工具。关于更新的信息，可以在Subversion的网站（<ulink
+ url="http://subversion.tigris.org/project_links.html"/>）查看。
</para>
</simplesect>
Modified: trunk/src/zh/book/book.xml
==============================================================================
--- trunk/src/zh/book/book.xml (original)
+++ trunk/src/zh/book/book.xml Wed Jan 25 01:01:34 2006
@@ -18,7 +18,7 @@
<!ENTITY appa SYSTEM "appa.xml">
<!ENTITY appb SYSTEM "appb.xml">
<!ENTITY appc SYSTEM "appc.xml">
-<!ENTITY appd SYSTEM "appd.xml">
+
<!ENTITY glossary SYSTEM "glossary.xml">
<!ENTITY license SYSTEM "copyright.xml">
@@ -29,7 +29,7 @@
<!-- Using revnumber would be more appropriate, but our stylesheets -->
<!-- don't seem to render it. -->
- <subtitle>针对 Subversion 1.1</subtitle><subtitle>（本书编译对应&svn.version;修订版本）</subtitle>
+ <subtitle>针对 Subversion 1.2</subtitle><subtitle>（本书编译对应&svn.version;修订版本）</subtitle>
<bookinfo>
@@ -76,7 +76,8 @@
<holder>C. Michael Pilato</holder>
</copyright>
- <legalnotice><para>本书使用创作共用署名许可证，可以通过访问http://creativecommons.org/licenses/by/2.0/或者发送邮件到Creative Commons,
+ <legalnotice><para>本书使用创作共用署名许可证，可以通过访问<ulink
+ url="http://creativecommons.org/licenses/by/2.0/"/>或者发送邮件到Creative Commons,
559 Nathan Abbott Way, Stanford,
California 94305, USA来查看本许可证的内容。</para></legalnotice>
@@ -98,7 +99,6 @@
&appa;
&appb;
&appc;
- &appd;
&license;
&glossary;
Modified: trunk/src/zh/book/ch00.xml
==============================================================================
--- trunk/src/zh/book/ch00.xml (original)
+++ trunk/src/zh/book/ch00.xml Wed Jan 25 01:01:34 2006
@@ -13,7 +13,7 @@
<para>但是像许多其他工具一样，CVS开始显露出衰老的迹象。Subversion是一个被设计成为CVS继任者的新版本控制系统。设计者通过两个办法来争取现有的CVS用户： 使用它构建一个开源软件系统的版本控制过程，从感觉和体验上与CVS类似，同时Subversion努力弥补CVS许多明显的缺陷，结果就是不需要版本控制系统一个大的革新。Subversion是非常强大、有用及灵活的工具。</para>
- <para>这本书是为Subversion 1.1 系列撰写的，我们试图涵盖Subversion的所有内容，但是Subversion有一个兴盛和充满活力的开发社区，已经有许多特性和改进计划在新的版本中实现，可能会与目前这本书中的命令与细节不一致。
+ <para>这本书是为Subversion 1.2系列撰写的，我们试图涵盖Subversion的所有内容，但是Subversion有一个兴盛和充满活力的开发社区，已经有许多特性和改进计划在新的版本中实现，可能会与目前这本书中的命令与细节不一致。
</para>
</simplesect>
@@ -22,7 +22,7 @@
<!-- ================================================================= -->
<!-- ======================== SECTION 1 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-0-sect-1">
+ <sect1 id="svn.preface.audience">
<title>读者</title>
@@ -39,7 +39,7 @@
<!-- ================================================================= -->
<!-- ======================== SECTION 2 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-0-sect-2">
+ <sect1 id="svn.preface.howread">
<title>怎样阅读本书</title>
<para>这本书的目标读者非常的广泛—从从未使用过版本控制的新手到经验丰富的系统管理员。根据你的基础，特定的章节可能对你更有用，下面的内容可以看作是为各类用户提供的<quote>推荐阅读清单</quote>：</para>
@@ -48,46 +48,50 @@
<varlistentry>
<term>资深管理员</term>
<listitem>
- <para>假设你以前已经使用过CVS，希望得到一个Subversion服务器并且尽快运行起来，第5、6章将会告诉你怎样建立第一个版本库，并且使之在网络上可用，此后，根据你的CVS使用经验，第3章和附录A告诉你怎样使用Subversion客户端。</para>
+ <para>假设你以前已经使用过CVS，希望得到一个Subversion服务器并且尽快运行起来，<xref linkend="svn.reposadmin"/>和<xref
+ linkend="svn.serverconfig"/>将会告诉你怎样建立第一个版本库，并且使之在网络上可用，此后，根据你的CVS使用经验，<xref linkend="svn.tour"/>和<xref linkend="svn.forcvs"/>告诉你怎样使用Subversion客户端。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>新用户</term>
<listitem>
- <para>你的管理员已经为你准备好了Subversion服务，你将学习如何使用客户端。如果你没有使用过版本控制系统（像CVS），那么第2、3章是重要的介绍，如果你是CVS的老手，最好从第3章和附录A开始。</para>
+ <para>你的管理员已经为你准备好了Subversion服务，你将学习如何使用客户端。如果你没有使用过版本控制系统（像CVS），那么<xref linkend="svn.basic"/>和<xref
+ linkend="svn.tour"/>是重要的介绍，如果你是CVS的老手，最好从第3章和附录A开始。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>高级用户</term>
<listitem>
- <para>无论你只是个使用者还是管理员，最终你的项目会长大，你想通过Subversion作许多高级的事情，像如何使用分支和执行合并（第4章），怎样使用Subversion的属性支持，怎样配制运行参数（第7章）等等。第4、7章一开始并不重要，但你适应了基本操作之后一定要读一下。</para>
+ <para>无论你只是个使用者还是管理员，最终你的项目会长大，你想通过Subversion作许多高级的事情，像如何使用分支和执行合并（<xref
+ linkend="svn.branchmerge"/>），怎样使用Subversion的属性支持，怎样配制运行参数（<xref
+ linkend="svn.advanced"/>）等等。这两章一开始并不重要，但你适应了基本操作之后一定要读一下。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>开发者</term>
<listitem>
- <para>大概你已经很熟悉Subversion了，你想扩展它并在它的API基础之上开发新软件，第8章将是为你准备的。</para>
+ <para>大概你已经很熟悉Subversion了，你想扩展它并在它的API基础之上开发新软件，<xref linkend="svn.developer"/>将是为你准备的。</para>
</listitem>
</varlistentry>
</variablelist>
- <para>这本书以一个参考材料作为结束—第9章包括了所有命令的参考，这个附录包括了许多有用的主题，当你完成了本书的阅读，你会经常去看这个章节。</para>
+ <para>这本书以一个参考材料作为结束—<xref
+ linkend="svn.ref"/>包括了所有命令的参考，这个附录包括了许多有用的主题，当你完成了本书的阅读，你会经常去看这个章节。</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 3 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-0-sect-3">
+ <sect1 id="svn.preface.conventions">
<title>本书约定</title>
<para>这一部分包括书中各种约定。</para>
<!-- ***************************************************************** -->
- <sect2 id="svn-ch-0-sect-3.1">
+ <sect2 id="svn.preface.conventions.typo">
<title>排版习惯</title>
<variablelist>
@@ -118,7 +122,7 @@
</sect2>
<!-- ***************************************************************** -->
- <sect2 id="svn-ch-0-sect-3.2">
+ <sect2 id="svn.preface.conventions.icons">
<title>图标</title>
<note>
@@ -139,9 +143,8 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 4 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-0-sect-4">
+ <sect1 id="svn.preface.organization">
<title>本书组织结构</title>
<para>以下是章节和其中的内容介绍：</para>
@@ -149,56 +152,56 @@
<variablelist>
<varlistentry>
- <term>第1章，<emphasis>介绍</emphasis></term>
+ <term><xref linkend="svn.intro"/></term>
<listitem>
<para>记述了Subversion的历史与特性、架构、组件和安装方法，还包括一个快速入门指南。</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>第2章，<emphasis>基本概念</emphasis></term>
+ <term><xref linkend="svn.basic"/></term>
<listitem>
<para>解释了版本控制的基础知识，介绍了不同的版本模型，随同讲述了Subversion的版本库，工作拷贝和修订版本的概念。</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>第3章，<emphasis>指导教程</emphasis></term>
+ <term><xref linkend="svn.tour"/></term>
<listitem>
<para>带领你作为一个Subversion用户开始工作，示范了怎样使用Subversion获得、修改和提交数据。</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>第4章，<emphasis>分支和合并</emphasis></term>
+ <term><xref linkend="svn.branchmerge"/></term>
<listitem>
<para>讨论分支、合并与标签，包括一个最佳实践，通常的用例，怎样取消修改，以及怎样从一个分支转到另一个分支。</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>第5章，<emphasis>版本库管理</emphasis></term>
+ <term><xref linkend="svn.reposadmin"/></term>
<listitem>
<para>讲述Subversion版本库的基本概念，怎样建立、配置和维护版本库，以及你可以使用的工具。</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>第6章，<emphasis>配置服务器</emphasis></term>
+ <term><xref linkend="svn.serverconfig"/></term>
<listitem>
<para>解释了怎样配置Subversion服务器，以及三种访问版本库的方式，<literal>HTTP</literal>、<literal>svn</literal>协议和本地访问。这里也介绍了认证的细节，以及授权与匿名访问方式。</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>第7章，<emphasis>高级主题</emphasis></term>
+ <term><xref linkend="svn.advanced"/></term>
<listitem>
<para>研究Subversion客户配置文件，文件和目录属性，怎样<literal>忽略</literal>工作拷贝中的文件，怎样引入外部版本树到工作拷贝，最后介绍了如何掌握卖主分支。</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>第8章，<emphasis>开发者信息</emphasis></term>
+ <term><xref linkend="svn.developer"/></term>
<listitem>
<para>
介绍了Subversion的核心，Subversion文件系统，以及从程序员的角度如何看待工作拷贝的管理区域，介绍了如何使用公共APIs写程序使用Subversion，最重要的是，怎样投身到Subversion的开发当中去。
@@ -207,7 +210,7 @@
</varlistentry>
<varlistentry>
- <term>第9章，<emphasis>Subversion完全手册</emphasis></term>
+ <term><xref linkend="svn.ref"/></term>
<listitem>
<para>深入研究研究所有的命令，包括
<command>svn</command>、<command>svnadmin</command>、和<command>svnlook</command>以及大量的相关实例</para>
@@ -215,7 +218,7 @@
</varlistentry>
<varlistentry>
- <term>附录A，<emphasis>Subversion对于CVS用户</emphasis></term>
+ <term><xref linkend="svn.forcvs"/></term>
<listitem>
<para>
比较Subversion与CVS的异同点，消除多年使用CVS养出的坏习惯的建议，包括subversion版本号、标记版本的目录、离线操作、<command>update</command>与<command>status</command>、分支、标签、元数据、冲突和认证。
@@ -224,14 +227,7 @@
</varlistentry>
<varlistentry>
- <term>附录B，<emphasis>故障解决</emphasis></term>
- <listitem>
- <para>叙述常见的问题，以及使用和编译Subversion的难点。</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>附录C，<emphasis>WebDAV与自动版本化</emphasis></term>
+ <term><xref linkend="svn.webdav"/></term>
<listitem>
<para>
描述了WebDAV与DeltaV的细节，和怎样将你的Subversion版本库作为可读/写的DAV共享装载。</para>
@@ -239,7 +235,7 @@
</varlistentry>
<varlistentry>
- <term>附录D，<emphasis>第三方工具</emphasis></term>
+ <term><xref linkend="svn.3rdparty"/></term>
<listitem>
<para>
讨论一些支持和使用Subversion的工具，包括可选的客户端工具，版本库浏览工具等等。</para>
@@ -252,130 +248,13 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 4b ============================= -->
- <!-- ================================================================= -->
- <sect1 id="svn-ch-0-sect-4b">
- <title>Subversion 1.1的新特性</title>
-
- <para>本版图书覆盖了Subversion 1.1的新特性，下面是一个1.1主要变化的列表。
- </para>
-
- <variablelist>
-
- <varlistentry>
- <term>非数据库的版本库</term>
- <listitem>
- <para>现在可以创建不使用Berkeley DB数据库的版本库，作为替代，这个新的版本库使用普通的文件系统，使用自定义的文件格式，这个版本库不是一个脆弱的<quote>楔入</quote>，它和Berkeley DB版本库一样经过很好的测试，见<xref
- linkend="svn-ch-5-sect-1.3"/>。</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>对象链接纳入版本控制</term>
- <listitem>
- <para>Unix用户可以创建一个对象链接，使用<command>svn
- add</command>放置到版本控制，见<xref
- linkend="svn-ch-9-sect-1.2-re-add"/>和<xref
- linkend="svn-ch-7-sect-2.3.7"/>。</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>客户可以追踪拷贝和改名</term>
- <listitem>
- <para>文件和目录的分支（拷贝）维护着他们与历史的联系，但是在Subversion 1.0中<command>svn log</command>追踪历史的方式与<command>svn
- diff</command>、<command>svn merge</command>、<command>svn
- list</command>或<command>svn cat</command>都不同，在Subversion 1.1，所有的客户端子命令可以透明的回溯到拷贝和改名之前的历史文件和目录。</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>客户端自动转化URI和IRI</term>
- <listitem>
- <para>在1.0的命令行客户端，用户需要手工的回避URL，客户端只能接收<quote>合法正确的</quote>URL，例如<literal>http://host/path%20with%20space/project/espa%F1a</literal>。1.1命令行客户端现在知道了web浏览器长久以来所做的事情：它会自动回避用户在shell放置的空格和重音字符之类的字符：<literal>"http://host/path with
- space/project/españa"</literal></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>本地化的用户信息</term>
- <listitem>
- <para>Subversion 1.1现在使用<literal>gettext()</literal>来为用户显示翻译的错误信息和帮助消息。现在有的翻译包括德国、西班牙、波兰、瑞典、繁体中文、日本、巴西、葡萄牙和挪威Bokmal，为了本地化你的Subversion客户端，只需要设置你的shell的LANG环境变量为支持的某个值（例如<literal>de_DE</literal>）。</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>可分享的工作拷贝</term>
- <listitem>
- <para>允许多个用户分享一个工作拷贝有一些历史问题，现在相信已经修正了。
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>store-passwords</literal>运行变量</term>
- <listitem>
- <para>这是一个新的运行变量用来关闭密码缓存，所以服务器证书可以缓存，见<xref linkend="svn-ch-7-sect-1.3.2"/>。</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>优化和bug修正</term>
- <listitem>
- <para><command>svn checkout</command>、<command>svn
- update</command>、<command>svn status</command>和
- <command>svn blame</command>会更快，超过50个小bug被修正，都在项目的CHANGES文件（在<systemitem
- class="url">http://svn.collab.net/repos/svn/trunk/CHANGES
- </systemitem>）里描述。</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>新的命令选项</term>
- <listitem>
- <itemizedlist>
- <listitem><para><command>svn blame --verbose</command>:见
- <xref linkend="svn-ch-9-sect-1.2-re-blame"/>.
- </para></listitem>
-
- <listitem><para><command>svn export --native-eol EOL</command>:见
- <xref linkend="svn-ch-9-sect-1.2-re-export"/>.
- </para></listitem>
-
- <listitem><para><command>svn add --force</command>:见
- <xref linkend="svn-ch-9-sect-1.2-re-add"/>.
- </para></listitem>
-
- <listitem><para><command>svnadmin dump --deltas</command>:见
- <xref linkend="svn-ch-5-sect-3.5"/>.
- </para></listitem>
-
- <listitem><para><command>svnadmin create --fs-type TYPE</command>:见
- <xref linkend="svn-ch-9-sect-2.2-re-create"/>.
- </para></listitem>
-
- <listitem><para><command>svnadmin recover --wait</command>:见
- <xref linkend="svn-ch-9-sect-2.2-re-recover"/>.
- </para></listitem>
-
- <listitem><para><command>svnserve --tunnel-user=NAME</command>:见
- <xref linkend="svn-ch-9-sect-4.1"/>.
- </para></listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect1>
-
- <!-- ================================================================= -->
<!-- ======================== SECTION 5 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-0-sect-5">
+ <sect1 id="svn.preface.free">
<title>这本书是免费的</title>
<para>
- 这本书是作为Subversion项目的文档，由开发者开始撰写的，后来成为一个独立工作并进行了重写，因此，它一直有一个免费许可证（见<xref linkend="svn-copyright"/>。）实际上，这本书是在公众关注中写出来的，作为Subversion的一部分，它有两种含义：</para>
+ 这本书是作为Subversion项目的文档，由开发者开始撰写的，后来成为一个独立工作并进行了重写，因此，它一直有一个免费许可证（见<xref linkend="svn.copyright"/>。）实际上，这本书是在公众关注中写出来的，作为Subversion的一部分，它有两种含义：</para>
<itemizedlist>
<listitem>
@@ -384,21 +263,20 @@
<listitem>
<para>
- 对于这本书，你可以任意分发或者修改—它是免费许可证，当然，相对于发布你的私有版本，你最好向Subversion开发社区提供反馈。为了能够参与到社区，见<xref linkend="svn-ch-8-sect-6"/>来学习如何加入到社区。</para>
+ 对于这本书，你可以任意分发或者修改—它是免费许可证，当然，相对于发布你的私有版本，你最好向Subversion开发社区提供反馈。为了能够参与到社区，见<xref linkend="svn.developer.contrib"/>来学习如何加入到社区。</para>
</listitem>
</itemizedlist>
-
+ <!-- O'Reilly Hardcopy Only
<para>你可以向O'Reilly发布评论和问题：###insert boilerplate.</para>
-
- <para>一个相对新的在线版本可以在<systemitem
- class="url">http://svnbook.red-bean.com</systemitem>找到。</para>
+ -->
+ <para>一个相对新的在线版本可以在<ulink url="http://svnbook.red-bean.com"/>找到。</para>
</sect1>
<!-- ================================================================= -->
<!-- ======================== SECTION 6 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-0-sect-6">
+ <sect1 id="svn.preface.acks">
<title>致谢</title>
<para>
@@ -430,7 +308,7 @@
Blair Zajac, 以及整个Subversion社区。</para>
<!-- ***************************************************************** -->
- <sect2 id="svn-ch-0-sect-6.1">
+ <sect2 id="svn.preface.acks.sussman">
<title>来自Ben Collins-Sussman</title>
<para>感谢我的妻子Frances，在几个月里，我一直在对你说，<quote>但是亲爱的，我还在为这本书工作</quote>，非比寻常，<quote>但是亲爱的，我还在处理邮件</quote>。我不知道她为什么会如此耐心！她是我完美的平衡点。</para>
@@ -442,7 +320,7 @@
</sect2>
<!-- ***************************************************************** -->
- <sect2 id="svn-ch-0-sect-6.2">
+ <sect2 id="svn.preface.acks.fitz">
<title>来自Brian W. Fitzpatrick</title>
<para>
@@ -458,7 +336,7 @@
</sect2>
<!-- ***************************************************************** -->
- <sect2 id="svn-ch-0-sect-6.3">
+ <sect2 id="svn.preface.acks.cmpilato">
<title>来自C. Michael Pilato</title>
<para>
Modified: trunk/src/zh/book/ch01.xml
==============================================================================
--- trunk/src/zh/book/ch01.xml (original)
+++ trunk/src/zh/book/ch01.xml Wed Jan 25 01:01:34 2006
@@ -1,4 +1,4 @@
-<chapter id="svn-ch-1">
+<chapter id="svn.intro">
<title>介绍</title>
@@ -11,9 +11,8 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 1 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-1-sect-1">
+ <sect1 id="svn.intro.whatis">
<title>Subversion是什么？</title>
@@ -29,18 +28,18 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 2 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-1-sect-2">
+ <sect1 id="svn.intro.history">
<title>Subversion的历史</title>
<para>
- 早在2000年，CollabNet, Inc. (<systemitem
- class="url">http://www.collab.net</systemitem>) 开始寻找CVS替代产品的开发人员，CollabNet提供了一个协作软件套件SourceCast，它的一个组件是版本控制系统。尽管SourceCast在初始时使用CVS作为其版本控制系统，但是CVS的局限性在一开始就很明显，CollabNet知道迟早要找到一个更好的替代品。遗憾的是，CVS成为了开源世界<foreignphrase>事实上的</foreignphrase>标准，因为<emphasis>没有</emphasis>更好的产品，至少是没有可以自由使用的。所以CollabNet决定写一个新的版本控制系统，建立在CVS思想之上的，但是修正其错误和不合理的特性。</para>
+ 早在2000年，CollabNet, Inc. (<ulink url="http://www.collab.net"/>) 开始寻找CVS替代产品的开发人员，CollabNet提供了一个协作软件套件叫做CollabNet企业版（CEE）<footnote>
+ <para>也有一个针对小团队的CollabNet团队版（CTE）。</para>
+ </footnote>，它的一个组件是版本控制系统。尽管SourceCast在初始时使用CVS作为其版本控制系统，但是CVS的局限性在一开始就很明显，CollabNet知道迟早要找到一个更好的替代品。遗憾的是，CVS成为了开源世界<foreignphrase>事实上的</foreignphrase>标准，因为<emphasis>没有</emphasis>更好的产品，至少是没有可以自由使用的。所以CollabNet决定写一个新的版本控制系统，建立在CVS思想之上的，但是修正其错误和不合理的特性。</para>
<para>
- 2000年2月，他们联系<citetitle>Open Source Development with CVS</citetitle>(Coriolis, 1999)的作者Karl Fogel，并且询问他是否希望为这个新项目工作，巧合的是，当时Karl正在与朋友Jim Blandy讨论设计一个新的版本控制系统。在1995年，他们两个曾经开办一个提供CVS支持的公司Cyclic Software，尽管他们最终卖掉了公司，但还是天天使用CVS进行日常工作，在使用CVS时的挫折最终促使他们认真地去考虑如何管理标记版本的数据，而且他们当时不仅仅提出了<quote>Subversion</quote>这个名字，并且做出了Subversion版本库的基础设计。所以当CollabNet提出邀请的时候，Karl马上同意为这个项目工作，同时Jim也得到了他的雇主，RedHat软件赞助他到这个项目并提供了一个宽松的时间。CollabNet雇佣了Karl和Ben Collins Sussman，详细的设计从三月开始，在Behlendorf 、CollabNet、Jason Robbins 和 Greg Stein（当时是一个独立开发者，活跃在WebDAV/DeltaV系统规范阶段）的恰当激励的帮助下，Subversion很快吸引了许多活跃的开发者，结果是许多有CVS经验的人们很乐于有机会为这个项目做些事情。</para>
+ 2000年2月，他们联系<citetitle>Open Source Development with CVS</citetitle>(Coriolis, 1999)的作者Karl Fogel，并且询问他是否希望为这个新项目工作，巧合的是，当时Karl正在与朋友Jim Blandy讨论设计一个新的版本控制系统。在1995年，他们两个曾经开办一个提供CVS支持的公司Cyclic Software，尽管他们最终卖掉了公司，但还是天天使用CVS进行日常工作，在使用CVS时的挫折最终促使他们认真地去考虑如何管理标记版本的数据，而且他们当时不仅仅提出了<quote>Subversion</quote>这个名字，并且做出了Subversion版本库的基础设计。所以当CollabNet提出邀请的时候，Karl马上同意为这个项目工作，同时Jim也得到了他的雇主，Red Hat软件赞助他到这个项目并提供了一个宽松的时间。CollabNet雇佣了Karl和Ben Collins Sussman，详细的设计从三月开始，在Behlendorf 、CollabNet、Jason Robbins 和 Greg Stein（当时是一个独立开发者，活跃在WebDAV/DeltaV系统规范阶段）的恰当激励的帮助下，Subversion很快吸引了许多活跃的开发者，结果是许多有CVS经验的人们很乐于有机会为这个项目做些事情。</para>
<para>
最初的设计小组固定在简单的目标上，他们不想在版本控制方法学中开垦处女地，他们只是希望修正CVS，他们决定Subversion匹配CVS的特性，保留相同的开发模型，但不复制CVS明显的缺陷。尽管它不需要成为CVS的继任者，它也应该与CVS保持足够的相似性，使得CVS用户可以轻松的做出转换。</para>
@@ -54,15 +53,14 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 3 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-1-sect-3">
+ <sect1 id="svn.intro.features">
<title>Subversion的特性</title>
<para>
当讨论Subversion为版本控制领域带来的特性的时候，通过学习它在CVS基础上所作的改进会是比较有效的方法。如果你不熟悉CVS，你会不太明白所有的特性，如果你根本就不熟悉版本控制，你会瞪着眼无所适从，你最好首先阅读一下<xref
- linkend="svn-ch-2"/>，它提供了一个版本控制的简单介绍。</para>
+ linkend="svn.basic"/>，它提供了一个版本控制的简单介绍。</para>
<para>Subversion提供：</para>
@@ -137,15 +135,14 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 4 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-1-sect-4">
+ <sect1 id="svn.intro.architecture">
<title>Subversion的架构</title>
- <para><xref linkend="svn-ch-1-dia-1"/>从高处<quote>俯视</quote>Subersion的设计。</para>
+ <para><xref linkend="svn.intro.architecture.dia-1"/>从高处<quote>俯视</quote>Subersion的设计。</para>
- <figure id="svn-ch-1-dia-1">
+ <figure id="svn.intro.architecture.dia-1">
<title>Subversion的架构</title>
<graphic fileref="images/ch01dia1.png"/>
</figure>
@@ -156,29 +153,26 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 5 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-1-sect-5">
+ <sect1 id="svn.intro.install">
<title>安装Subversion</title>
<para>
- Subversion建立在一个可移植层上，叫做APR（Apache Portable Runtime library），这意味着Subversion可以在所有可运行Apache服务器的平台上工作：Windows、Linux、各种BSD、Mac OS X、Netware以及其他。</para>
+ Subversion建立在一个可移植层上，叫做APR—Apache Portable Runtime library，APR库提供了许多Subversion在多种操作系统上需要的功能：磁盘访问、内存管理等等。虽然Subversion可以使用Apache作为服务器程序，这种对APR的依赖并不意味着Apache是必需的组件，APR是可以独立使用的库。这意味着Subversion可以在所有可运行Apache服务器的平台上工作：Windows、Linux、各种BSD、Mac OS X、Netware以及其他。</para>
<para>
- 最简单的安装办法就是下载相应操作系统的二进制包，Subversion的网站（<systemitem
- class="url">http://subversion.tigris.org</systemitem>）上通常会有志愿者提供的包可以下载，对于微软操作系统，网站上通常会有图形化的安装包，对于类Unix系统，你可以使用它们本身的打包系统（PRMs、DEBs、ports tree等等）得到Subversion。</para>
+ 最简单的安装办法就是下载相应操作系统的二进制包，Subversion的网站（<ulink url="http://subversion.tigris.org"/>）上通常会有志愿者提供的包可以下载，对于微软操作系统，网站上通常会有图形化的安装包，对于类Unix系统，你可以使用它们本身的打包系统（PRMs、DEBs、ports tree等等）得到Subversion。</para>
<para>
你也可以选择从源代码直接编译Subversion，从网站下载最新的源代码，解压缩，根据<filename>INSTALL</filename>文件的指导进行编译。注意，通过这些源代码可以完全编译访问服务器的命令行客户端工具（通常是apr，apr-util和neno库）。但是可选部分有许多依赖，如Berkeley DB和Apache httpd。如果你希望做一个完全的编译，确定你有所有<filename>INSTALL</filename>文件中记述的包。如果你计划通过Subversiong本身工作，你可以使用客户端程序取得最新的，带血的源代码，这部分内容见<xref
- linkend="svn-ch-8-sect-6.2"/>。</para>
+ linkend="svn.developer.contrib.get-code"/>。</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 6 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-1-sect-6">
+ <sect1 id="svn.intro.components">
<title>Subversion的组件</title>
@@ -242,9 +236,8 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 7 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-1-sect-7">
+ <sect1 id="svn.intro.quickstart">
<title>快速入门</title>
@@ -252,11 +245,11 @@
许多人为<quote>从头到尾</quote>的方式读一本介绍有趣新技术的书感到发愁，这一小节是一个很短的介绍，给许多<quote>实用</quote>的用户一个实战的机会，如果你是一个喜欢通过实验进行学习的用户，以下将告诉你怎么做，相对应，我们给出这本书相关的链接。</para>
<para>
- 如果版本控制或者Subversion和CVS都用到的<quote>拷贝-修改-合并</quote>模型对于你来说是完全的新概念，在进一步阅读之前，你首先要读<xref linkend="svn-ch-2"/>。</para>
+ 如果版本控制或者Subversion和CVS都用到的<quote>拷贝-修改-合并</quote>模型对于你来说是完全的新概念，在进一步阅读之前，你首先要读<xref linkend="svn.basic"/>。</para>
<note>
<para>
- 以下的例子假定你有了<command>svn</command>这个客户端程序，也有<command>svnadmin</command>这个管理程序，你的<command>svn</command>也应该在Berkeley DB的基础上进行编译。为了验证这些，运行<command>svn --version</command>，确定ra_local模块存在，如果没有，这个程序不能访问<literal>file://</literal>的URL。</para>
+ 以下的例子假定你有了1.2或更新的Subversion程序（运行<command>svn --version</command>来检查版本）。</para>
</note>
<para>
@@ -269,50 +262,95 @@
</screen>
<para>
- 这个命令建立了一个新的目录 <filename>/path/to/repos</filename>，包含了一个Subversion版本库。确定这个目录在本地磁盘上，而<emphasis>不是</emphasis>一个网络共享，这个新的目录保存着一些Berkeley DB的数据库文件，你打开后看不到你的已经版本化的文件。更多的版本库创建和维护信息，见第5章<xref linkend="svn-ch-5"/>。</para>
+ 这个命令建立了一个新的目录 <filename>/path/to/repos</filename>，包含了一个Subversion版本库。这个目录保存了一些数据库文件，你打开后看不到你的已经版本化的文件。更多的版本库创建和维护信息，见<xref linkend="svn.reposadmin"/>。</para>
- <para>第二步，建立一些将要导入到版本库的文件与目录，为了以后使用更清楚（见<xref linkend="svn-ch-4"/>），你的文件应该包括三个顶级子目录，分别是<filename>branches</filename>、<filename>tags</filename>和<filename>trunk</filename>：</para>
+ <para>Subversion has no concept of a <quote>project</quote>. The
+ repository is just a virtual versioned filesystem, a large tree
+ that can hold anything you wish. Some administrators prefer to
+ store only one project in a repository, and others prefer to
+ store multiple projects in a repository by placing them into
+ separate directories. The merits of each approach are discussed
+ in <xref linkend="svn.reposadmin.projects.chooselayout"/>.
+ Either way, the repository only manages files and directories,
+ so it's up to humans to interpret particular directories
+ as <quote>projects</quote>. So while you might see references
+ to projects throughout this book, keep in mind that we're only
+ ever talking about some directory (or collection of directories)
+ in the repository.</para>
+
+ <para>In this example, we assume that you already have some sort
+ of project (a collection of files and directories) that you wish
+ to import into your newly created Subversion repository. Begin
+ by organizing them into a single directory
+ called <filename>myproject</filename> (or whatever you wish).
+ For reasons that will be clear later (see
+ <xref linkend="svn.branchmerge"/>), your project's tree
+ structure should contain three top-level directories
+ named <filename>branches</filename>,
+ <filename>tags</filename>, and
+ <filename>trunk</filename>. The <filename>trunk</filename>
+ directory should contain all of your data,
+ while <filename>branches</filename>
+ and <filename>tags</filename> directories are empty:</para>
<screen>
-/tmp/project/branches/
-/tmp/project/tags/
-/tmp/project/trunk/
- foo.c
- bar.c
- Makefile
- …
+/tmp/myproject/branches/
+/tmp/myproject/tags/
+/tmp/myproject/trunk/
+ foo.c
+ bar.c
+ Makefile
+ …
</screen>
- <para>
- 一旦你有了树形结构和数据你就可以继续了，使用<command>svn import</command>导入数据到版本库（见<xref linkend="svn-ch-3-sect-7.3"/>部分）：</para>
+ <para>The <filename>branches</filename>, <filename>tags</filename>,
+ and <filename>trunk</filename> subdirectories aren't actually
+ required by Subversion. They're merely a popular convention
+ that you'll most likely want to use later on.</para>
+
+ <para>Once you have your tree of data ready to go, import it into
+ the repository with the <command>svn import</command> command
+ (see <xref linkend="svn.tour.other.import"/>):</para>
<screen>
-$ svn import /tmp/project file:///path/to/repos -m "initial import"
-Adding /tmp/project/branches
-Adding /tmp/project/tags
-Adding /tmp/project/trunk
-Adding /tmp/project/trunk/foo.c
-Adding /tmp/project/trunk/bar.c
-Adding /tmp/project/trunk/Makefile
+$ svn import /tmp/myproject file:///path/to/repos/myproject -m "initial import"
+Adding /tmp/myproject/branches
+Adding /tmp/myproject/tags
+Adding /tmp/myproject/trunk
+Adding /tmp/myproject/trunk/foo.c
+Adding /tmp/myproject/trunk/bar.c
+Adding /tmp/myproject/trunk/Makefile
…
Committed revision 1.
$
</screen>
- <para>
- 现在版本库已经包含你的目录和数据了，注意原先的<filename>/tmp/project</filename>目录没有任何变化；Subversion不管这个，（事实上，你甚至可以任意删除这个目录）。为了处理 版本库的数据，你需要创建一个新的包含数据的<quote>工作拷贝</quote>，一个私人的工作空间。告诉Subversion来<quote>取出</quote>版本库的<filename>trunk</filename>目录：</para>
+ <para>Now the repository contains this tree of data. As mentioned
+ earlier, you won't see your files by directly peeking into the
+ repository; they're all stored within a database. But the
+ repository's imaginary filesystem now contains a top-level
+ directory named <filename>myproject</filename>, which in turn
+ contains your data.</para>
+
+ <para>Note that the original <filename>/tmp/myproject</filename>
+ directory is unchanged; Subversion is unaware of it. (In fact,
+ you can even delete that directory if you wish.) In order to
+ start manipulating repository data, you need to create a new
+ <quote>working copy</quote> of the data, a sort of private
+ workspace. Ask Subversion to <quote>check out</quote> a working
+ copy of the <filename>myproject/trunk</filename> directory in
+ the repository:</para>
<screen>
-$ svn checkout file:///path/to/repos/trunk project
-A project/foo.c
-A project/bar.c
-A project/Makefile
+$ svn checkout file:///path/to/repos/myproject/trunk myproject
+A myproject/foo.c
+A myproject/bar.c
+A myproject/Makefile
…
Checked out revision 1.
</screen>
-
<para>
- 你现在在<filename>project</filename>目录里有了一个版本库的个人拷贝，你可以编辑你的工作备份中的文件，并且提交到版本库。</para>
+ 你现在在<filename>myproject</filename>目录里有了一个版本库的个人拷贝，你可以编辑你的工作备份中的文件，并且提交到版本库。</para>
<itemizedlist>
<listitem>
@@ -329,11 +367,11 @@
</listitem>
</itemizedlist>
- <para>对于你对工作拷贝可做操作的完全教程可以察看<xref linkend="svn-ch-3"/>。</para>
+ <para>对于你对工作拷贝可做操作的完全教程可以察看<xref linkend="svn.tour"/>。</para>
<para>
目前，你可以选择使你的版本库在网络上可见，可以参考<xref
- linkend="svn-ch-6"/>，学习使用不同的服务器以及配置。</para>
+ linkend="svn.serverconfig"/>，学习使用不同的服务器以及配置。</para>
</sect1>
Modified: trunk/src/zh/book/ch02.xml
==============================================================================
--- trunk/src/zh/book/ch02.xml (original)
+++ trunk/src/zh/book/ch02.xml Wed Jan 25 01:01:34 2006
@@ -1,4 +1,4 @@
-<chapter id="svn-ch-2">
+<chapter id="svn.basic">
<title>基本概念</title>
<simplesect>
@@ -9,15 +9,17 @@
尽管我们的例子展示了人们如何分享程序源代码，仍然要记住Subversion可以控制所有类型的文件—它并没有限制在只为程序员工作。</para>
</simplesect>
-
- <sect1 id="svn-ch-2-sect-1">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.basic.repository">
<title>版本库</title>
<para>
Subversion是一种集中的分享信息的系统，它的核心是版本库，它储存所有的数据，版本库按照<firstterm>文件树</firstterm>形式储存数据—包括文件和目录。任意数量的<firstterm>客户端</firstterm>可以连接到版本库，读写这些文件。通过写，别人可以看到这些信息，通过读数据，可以看到别人的修改。<xref
- linkend="svn-ch-2-dia-1"/>描述了这种关系：</para>
+ linkend="svn.basic.repository.dia-1"/>描述了这种关系：</para>
- <figure id="svn-ch-2-dia-1">
+ <figure id="svn.basic.repository.dia-1">
<title>一个典型的客户/服务器系统</title>
<graphic fileref="images/ch02dia1.png"/>
</figure>
@@ -30,13 +32,17 @@
</para>
</sect1>
- <sect1 id="svn-ch-2-sect-2">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.basic.vsn-models">
<title>版本模型</title>
<para>
版本控制系统的核心任务是提供协作编辑和数据共享，但是不同的系统使用不同的策略来达到目的。</para>
- <sect2 id="svn-ch-2-sect-2.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.basic.vsn-models.problem-sharing">
<title>文件共享的问题</title>
<para>
@@ -44,23 +50,23 @@
<para>
考虑<xref
- linkend="svn-ch-2-dia-2"/>的情景，我们有两个共同工作者，Harry和Sally，他们想同时编辑版本库里的同一个文件，如果首先Harry保存它的修改，过了一会，Sally可能凑巧用自己的版本覆盖了这些文件，Harry的更改不会永远消失（因为系统记录了每次修改），Harry所有的修改<emphasis>不会</emphasis>出现在Sally的文件中，所以Harry的工作还是丢失了—至少是从最新的版本中丢失了—而且是意外的，这就是我们要明确避免的情况！</para>
+ linkend="svn.basic.vsn-models.problem-sharing.dia-1"/>的情景，我们有两个共同工作者，Harry和Sally，他们想同时编辑版本库里的同一个文件，如果首先Harry保存它的修改，过了一会，Sally可能凑巧用自己的版本覆盖了这些文件，Harry的更改不会永远消失（因为系统记录了每次修改），Harry所有的修改<emphasis>不会</emphasis>出现在Sally的文件中，所以Harry的工作还是丢失了—至少是从最新的版本中丢失了—而且是意外的，这就是我们要明确避免的情况！</para>
- <figure id="svn-ch-2-dia-2">
+ <figure id="svn.basic.vsn-models.problem-sharing.dia-1">
<title>需要避免的问题</title>
<graphic fileref="images/ch02dia2.png"/>
</figure>
</sect2>
- <sect2 id="svn-ch-2-sect-2.2">
+ <sect2 id="svn.basic.vsn-models.lock-unlock">
<title>锁定-修改-解锁 方案</title>
<para>
许多版本控制系统使用<firstterm>锁定-修改-解锁</firstterm>这种机制解决这种问题，在这样的系统里，在一个时间段里版本库的一个文件只允许被一个人修改。首先在修改之前，Harry要<quote>锁定</quote>住这个文件，锁定很像是从图书馆借一本书，如果Harry锁住这个文件，Sally不能做任何修改，如果Sally想请求得到一个锁，版本库会拒绝这个请求。在Harry结束编辑并且放开这个锁之前，她只可以阅读文件。Harry解锁后，就要换班了，Sally得到自己的轮换位置，锁定并且开始编辑这个文件。<xref
- linkend="svn-ch-2-dia-3"/>描述了这样的解决方案。</para>
+ linkend="svn.basic.vsn-models.lock-unlock.dia-1"/>描述了这样的解决方案。</para>
- <figure id="svn-ch-2-dia-3">
+ <figure id="svn.basic.vsn-models.lock-unlock.dia-1">
<title>锁定-修改-解锁 方案</title>
<graphic fileref="images/ch02dia3.png"/>
</figure>
@@ -83,7 +89,8 @@
</sect2>
- <sect2 id="svn-ch-2-sect-2.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.basic.vsn-models.copy-merge">
<title>拷贝-修改-合并 方案</title>
<para>
@@ -91,14 +98,14 @@
<para>
这是一个例子，Harry和Sally为同一个项目各自建立了一个工作拷贝，工作是并行的，修改了同一个文件A，Sally首先保存修改到版本库，当Harry想去提交修改的时候，版本库提示文件A已经<firstterm>过期</firstterm>，换句话说，A在他上次更新之后已经更改了，所以当他通过客户端请求<firstterm>合并</firstterm>版本库和他的工作拷贝之后，碰巧Sally的修改和他的不冲突，所以一旦他把所有的修改集成到一起，他可以将工作拷贝保存到版本库，<xref
- linkend="svn-ch-2-dia-4"/>和<xref linkend="svn-ch-2-dia-5"/>展示了这一过程。</para>
+ linkend="svn.basic.vsn-models.copy-merge.dia-1"/>和<xref linkend="svn.basic.vsn-models.copy-merge.dia-2"/>展示了这一过程。</para>
- <figure id="svn-ch-2-dia-4">
+ <figure id="svn.basic.vsn-models.copy-merge.dia-1">
<title>拷贝-修改-合并 方案</title>
<graphic fileref="images/ch02dia4.png"/>
</figure>
- <figure id="svn-ch-2-dia-5">
+ <figure id="svn.basic.vsn-models.copy-merge.dia-2">
<title>拷贝-修改-合并 方案（续）</title>
<graphic fileref="images/ch02dia5.png"/>
</figure>
@@ -112,27 +119,54 @@
<para>
最后，一切都要归结到一条重要的因素：用户交流。当用户交流贫乏，语法和语义的冲突就会增加，没有系统可以强制用户完美的交流，没有系统可以检测语义上的冲突，所以没有任何证据能够承诺锁定系统可以防止冲突，实践中，锁定除了约束了生产力，并没有做什么事。</para>
+ <sidebar id="svn.basic.vsn-models.copy-merge.sb-1">
+ <title>When Locking is Necessary</title>
+
+ <para>While the lock-modify-unlock model is considered
+ generally harmful to collaboration, there are still times
+ when locking is appropriate.</para>
+
+ <para>The copy-modify-merge model is based on the assumption
+ that files are contextually mergeable: that is, that the
+ majority of the files in the repository are line-based text
+ files (such as program source code). But for files with
+ binary formats, such as artwork or sound, it's often
+ impossible to merge conflicting changes. In these
+ situations, it really is necessary to users to take strict
+ turns when changing the file. Without serialized access,
+ somebody ends up wasting time on changes that are ultimately
+ discarded.</para>
+
+ <para>While CVS and Subversion are still primarily
+ copy-modify-merge systems, they both recognize the need to
+ lock an occasional file and provide mechanisms for this.
+ See <xref linkend="svn.advanced.locking"/>.</para>
+
+ </sidebar>
</sect2>
</sect1>
- <!-- How svn implements the philosophy -->
- <sect1 id="svn-ch-2-sect-3">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.basic.in-action">
<title>Subversion实战</title>
<para>
是时候从抽象转到具体了，在本小节，我们会展示一个Subversion真实使用的例子。</para>
- <sect2 id="svn-ch-2-sect-3.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.basic.in-action.wc">
<title>工作拷贝</title>
<para>
你已经阅读过了关于工作拷贝的内容，现在我们要讲一讲客户端怎样建立和使用它。</para>
<para>
- 一个Subversion工作拷贝是你本地机器一个普通的目录，保存着一些文件，你可以任意的编辑文件，而且如果是源代码文件，你可以像平常一样编译，你的工作拷贝是你的私有工作区，在你明确的做了特定操作之前，Subversion不会把你的修改与其他人的合并，也不会把你的修改展示给别人。</para>
+ 一个Subversion工作拷贝是你本地机器一个普通的目录，保存着一些文件，你可以任意的编辑文件，而且如果是源代码文件，你可以像平常一样编译，你的工作拷贝是你的私有工作区，在你明确的做了特定操作之前，Subversion不会把你的修改与其他人的合并，也不会把你的修改展示给别人，你甚至可以拥有同一个项目的多个工作拷贝。</para>
<para>
当你在工作拷贝作了一些修改并且确认它们工作正常之后，Subversion提供了一个命令可以<quote>发布</quote>你的修改给项目中的其他人（通过写到版本库），如果别人发布了各自的修改，Subversion提供了手段可以把这些修改与你的工作目录进行合并（通过读取版本库）。</para>
@@ -145,9 +179,9 @@
<para>
举一个例子，你的版本库包含两个软件项目，<literal>paint</literal>和<literal>calc</literal>。每个项目在它们各自的顶级子目录下，见<xref
- linkend="svn-ch-2-dia-6"/>。</para>
+ linkend="svn.basic.in-action.wc.dia-1"/>。</para>
- <figure id="svn-ch-2-dia-6">
+ <figure id="svn.basic.in-action.wc.dia-1">
<title>版本库的文件系统</title>
<graphic fileref="images/ch02dia6.png"/>
</figure>
@@ -158,10 +192,10 @@
<screen>
$ svn checkout http://svn.example.com/repos/calc
-A calc
-A calc/Makefile
-A calc/integer.c
-A calc/button.c
+A calc/Makefile
+A calc/integer.c
+A calc/button.c
+Checked out revision 56.
$ ls -A calc
Makefile integer.c button.c .svn/
@@ -170,13 +204,13 @@
<para>
列表中的A表示Subversion增加了一些条目到工作拷贝，你现在有了一个<filename>/calc</filename>的个人拷贝，有一个附加的目录—<filename>.svn</filename>—保存着前面提及的Subversion需要的额外信息。</para>
- <sidebar id="svn-ch-2-sidebar-1">
+ <sidebar id="svn.basic.in-action.wc.sb-1">
<title>版本库的URL</title>
<para>
- Subversion可以通过多种方式访问—本地磁盘访问，或各种各样不同的网络协议，但一个版本库地址永远都是一个URL，表格2.1描述了不同的URL模式对应的访问方法。</para>
+ Subversion可以通过多种方式访问—本地磁盘访问，或各种各样不同的网络协议，但一个版本库地址永远都是一个URL，<xref linkend="svn.basic.in-action.wc.tbl-1"/>描述了不同的URL模式对应的访问方法。</para>
- <table id="svn-ch-2-table-1">
+ <table id="svn.basic.in-action.wc.tbl-1">
<title>版本库访问URL</title>
<tgroup cols="2">
<thead>
@@ -210,7 +244,7 @@
</tgroup>
</table>
- <para>关于Subversion解析URL的更多信息，见<xref linkend="svn-ch-7-sect-6"/>。</para>
+ <para>关于Subversion解析URL的更多信息，见<xref linkend="svn.advanced.reposurls"/>。</para>
</sidebar>
@@ -221,7 +255,7 @@
<para>
发布你的修改给别人，你可以使用Subversion的提交（<command>commit</command>）命令：</para>
-<screen>
+ <screen>
$ svn commit button.c
Sending button.c
Transmitting file data .
@@ -237,7 +271,7 @@
<para>
要使项目最新，Sally可以要求Subversion<firstterm>更新</firstterm>她的工作备份，通过使用更新（<command>update</command>）命令，将结合你和所有其他人在她上次更新之后的改变到她的工作拷贝。</para>
-<screen>
+ <screen>
$ pwd
/home/sally/calc
@@ -245,7 +279,8 @@
.svn/ Makefile integer.c button.c
$ svn update
-U button.c
+U button.c
+Updated to revision 57.
</screen>
<para>
@@ -254,7 +289,8 @@
</sect2>
- <sect2 id="svn-ch-2-sect-3.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.basic.in-action.revs">
<title>修订版本</title>
<para>
@@ -267,9 +303,9 @@
每当版本库接受了一个提交，文件系统进入了一个新的状态，叫做一次修订（<firstterm>revision</firstterm>），每一个修订版本被赋予一个独一无二的自然数，一个比一个大，初始修订号是0，只创建了一个空目录，没有任何内容。</para>
<para>
- <xref linkend="svn-ch-2-dia-7"/>可以更形象的描述版本库，想象有一组修订号，从0开始，从左到右，每一个修订号有一个目录树挂在它下面，每一个树好像是一次提交后的版本库<quote>快照</quote>。</para>
+ <xref linkend="svn.basic.in-action.revs.dia-1"/>可以更形象的描述版本库，想象有一组修订号，从0开始，从左到右，每一个修订号有一个目录树挂在它下面，每一个树好像是一次提交后的版本库<quote>快照</quote>。</para>
- <figure id="svn-ch-2-dia-7">
+ <figure id="svn.basic.in-action.revs.dia-1">
<title>版本库</title>
<graphic fileref="images/ch02dia7.png"/>
</figure>
@@ -278,13 +314,13 @@
<title>全局修订号</title>
<para>
- 不像其他版本控制系统，Subversion的修订号是针对整个<emphasis>目录树</emphasis>的，而不是单个文件。每一个修订号代表了一次提交后版本库整个目录树的特定状态，另一种理解是修订号N代表版本库已经经过了N次提交。当Subversion用户讨论<quote><filename>foo.c</filename>的修订号5</quote>时，他们的实际意思是<quote>在修订号5时的<filename>foo.c</filename></quote>。需要注意的是，修订号N和M并<emphasis>不</emphasis>表示一个文件需要不同。因为CVS使用每一个文件一个修订号的策略，CVS用户可能希望察看<xref linkend="svn-ap-a"/>来得到更多细节。</para>
+ 不像其他版本控制系统，Subversion的修订号是针对整个<emphasis>目录树</emphasis>的，而不是单个文件。每一个修订号代表了一次提交后版本库整个目录树的特定状态，另一种理解是修订号N代表版本库已经经过了N次提交。当Subversion用户讨论<quote><filename>foo.c</filename>的修订号5</quote>时，他们的实际意思是<quote>在修订号5时的<filename>foo.c</filename></quote>。需要注意的是，修订号N和M并<emphasis>不</emphasis>表示一个文件需要不同。因为CVS使用每一个文件一个修订号的策略，CVS用户可能希望察看<xref linkend="svn.forcvs"/>来得到更多细节。</para>
</sidebar>
<para>
需要特别注意的是，工作拷贝并不一定对应版本库中的单个修订版本，他们可能包含多个修订版本的文件。举个例子，你从版本库检出一个工作拷贝，最近的修订号是4：</para>
-<screen>
+ <screen>
calc/Makefile:4
integer.c:4
button.c:4
@@ -293,7 +329,7 @@
<para>
此刻，工作目录与版本库的修订版本4完全对应，然而，你修改了<filename>button.c</filename>并且提交之后，假设没有别的提交出现，你的提交会在版本库建立修订版本5，你的工作拷贝会是这个样子的：</para>
-<screen>
+ <screen>
calc/Makefile:4
integer.c:4
button.c:5
@@ -302,7 +338,7 @@
<para>
假设此刻，Sally提交了对<filename>integer.c</filename>的修改，建立修订版本6，如果你使用<command>svn update</command>来更新你的工作拷贝，你会看到：</para>
-<screen>
+ <screen>
calc/Makefile:6
integer.c:6
button.c:6
@@ -314,7 +350,8 @@
</sect2>
- <sect2 id="svn-ch-2-sect-3.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.basic.in-action.track-repos">
<title>工作拷贝怎样追踪版本库</title>
<para>
@@ -375,34 +412,151 @@
<para>
- 这看起来需要记录很多事情，但是<command>svn status</command>命令可以告诉你工作拷贝中文件的状态，关于此命令更多的信息，请看<xref linkend="svn-ch-3-sect-5.3.1" />。</para>
+ 这看起来需要记录很多事情，但是<command>svn status</command>命令可以告诉你工作拷贝中文件的状态，关于此命令更多的信息，请看<xref linkend="svn.tour.cycle.examine.status" />。</para>
</sect2>
- <sect2 id="svn-ch-2-sect-3.4">
- <title>修订版本混合的限制</title>
+ <!-- =============================================================== -->
+ <sect2 id="svn.basic.in-action.mixedrevs">
+ <title>混合修订版本的工作拷贝</title>
+
+ <para>As a general principle, Subversion tries to be as flexible
+ as possible. One special kind of flexibility is the ability
+ to have a working copy containing files and directories with a
+ mix of different working revision numbers. Unfortunately,
+ this flexibility tends to confuse a number of new users. If
+ the earlier example showing mixed revisions perplexed you,
+ here's a primer on both why the feature exists and how to make
+ use of it.</para>
+
+ <sect3 id="svn.basic.in-action.mixedrevs.update-commit">
+ <title>Updates and Commits are Separate</title>
+
+ <para>One of the fundamental rules of Subversion is that
+ a <quote>push</quote> action does not cause
+ a <quote>pull</quote>, nor the other way around. Just
+ because you're ready to submit new changes to the repository
+ doesn't mean you're ready to receive changes from other
+ people. And if you have new changes still in progress,
+ then <command>svn update</command> should gracefully merge
+ repository changes into your own, rather than forcing you to
+ publish them.</para>
+
+ <para>The main side-effect of this rule is that it means a
+ working copy has to do extra bookkeeping to track mixed
+ revisions, and be tolerant of the mixture as well. It's
+ made more complicated by the fact that directories
+ themselves are versioned.</para>
+
+ <para>For example, suppose you have a working copy entirely at
+ revision 10. You edit the
+ file <filename>foo.html</filename> and then perform
+ an <command>svn commit</command>, which creates revision 15
+ in the repository. After the commit succeeds, many new
+ users would expect the working copy to be entirely at
+ revision 15, but that's not the case! Any number of changes
+ might have happened in the repository between revisions 10
+ and 15. The client knows nothing of those changes in the
+ repository, since you haven't yet run <command>svn
+ update</command>, and <command>svn commit</command> doesn't
+ pull down new changes. If, on the other hand,
+ <command>svn commit</command> <emphasis>were</emphasis> to
+ automatically download the newest changes, then it would be
+ possible to set the entire working copy to revision
+ 15—but then we'd be breaking the fundamental rule
+ of <quote>push</quote> and <quote>pull</quote> remaining
+ separate actions. Therefore the only safe thing the
+ Subversion client can do is mark the one
+ file—<filename>foo.html</filename>—as being at
+ revision 15. The rest of the working copy remains at
+ revision 10. Only by running <command>svn update</command>
+ can the latest changes be downloaded, and the whole working
+ copy be marked as revision 15.</para>
+
+ </sect3>
+
+ <sect3 id="svn.basic.in-action.mixedrevs.normal">
+ <title>Mixed revisions are normal</title>
+
+ <para>The fact is, <emphasis>every time</emphasis> you
+ run <command>svn commit</command>, your working copy ends
+ up with some mixture of revisions. The things you just
+ committed are marked as having larger working revisions
+ than everything else. After several commits (with no
+ updates in-between) your working copy will contain a whole
+ mixture of revisions. Even if you're the only person
+ using the repository, you will still see this phenomenon.
+ To examine your mixture of working revisions, use
+ the <command>svn status --verbose</command> command (see
+ <xref linkend="svn.tour.cycle.examine.status"/> for more
+ information.)</para>
+
+ <para>Often, new users are completely unaware that their
+ working copy contains mixed revisions. This can be
+ confusing, because many client commands are sensitive to
+ the working revision of the item they're examining. For
+ example, the <command>svn log</command> command is used to
+ display the history of changes to a file or directory (see
+ <xref linkend="svn.tour.history.log"/>). When the user
+ invokes this command on a working copy object, they expect
+ to see the entire history of the object. But if the
+ object's working revision is quite old (often
+ because <command>svn update</command> hasn't been run in a
+ long time), then the history of
+ the <emphasis>older</emphasis> version of the object is
+ shown.</para>
+ </sect3>
+
+ <sect3 id="svn.basic.in-action.mixedrevs.useful">
+ <title>Mixed revisions are useful</title>
+
+ <para>If your project is sufficiently complex, you'll
+ discover that it's sometimes nice to forcibly
+ <quote>backdate</quote> portions of your working copy to
+ an earlier revision; you'll learn how to do that in
+ Chapter 3. Perhaps you'd like to test an earlier version
+ of a sub-module contained in a subdirectory, or perhaps
+ you'd like to figure out when a bug first came into
+ existence in a specific file. This is the <quote>time
+ machine</quote> aspect of a version control system —
+ the feature which allows you to move any portion of your
+ working copy forward and backward in history.</para>
+
+ </sect3>
+
+ <sect3 id="svn.basic.in-action.mixedrevs.limits">
+ <title>Mixed revisions have limitations</title>
+
+ <para>However you make use of mixed revisions in your
+ working copy, there are limitations to this
+ flexibility.</para>
+
+ <para>First, you cannot commit the deletion of a file or
+ directory which isn't fully up-to-date. If a newer
+ version of the item exists in the repository, your attempt
+ to delete will be rejected, to prevent you from
+ accidentally destroying changes you've not yet
+ seen.</para>
+
+ <para>Second, you cannot commit a metadata change to a
+ directory unless it's fully up-to-date. You'll learn
+ about attaching
+ <quote>properties</quote> to items in Chapter 6. A
+ directory's working revision defines a specific set of
+ entries and properties, and thus committing a property
+ change to an out-of-date directory may destroy properties
+ you've not yet seen.</para>
- <para>作为通常的原则，Subversion期望尽可能的灵活，一个灵活性的表现就是能够在工作拷贝中混合有不同的修订版本。</para>
-
- <para>
- 起初，为什么把这种灵活性看作一种特性并没有完全看清楚，这也不是一个任务。完成了提交之后，干净的提交的文件比其他文件有更加新的版本，这看起来有些混乱，但是像以前说过的，通过<command>svn update</command>可以使整个版本统一起来， 怎么会有人<emphasis>故意的</emphasis>混合版本呢？</para>
-
- <para>
- 假设你的项目非常复杂，有时候需要强制地使工作拷贝的一部分<quote>回到</quote>某一个日期，你可以在第3章学习如何操作。或许你也希望测试某一目录下子模块早期的版本，或许你想检查某一文件过去的一系列版本在最新目录树环境下的表现。</para>
-
- <para>无论你在工作拷贝中如何利用混合版本，对于这种灵活性是有限制的。</para>
-
- <para>
- 首先，你不可以提交一个不是完全最新的文件或目录，如果有个新的版本存在于版本库，你的删除操作会被拒绝，这防止你不小心破坏你没有见到的东西。</para>
-
- <para>
- 第二，如果目录已经不是最新的了，你不能提交一个目录的元数据更改。你将会在第6章学习附加<quote>属性</quote>，一个目录的工作修订版本定义了许多条目和属性，因而对一个过期的版本提交属性会破坏一些你没有见到的属性。</para>
+ </sect3>
</sect2>
</sect1>
- <sect1 id="svn-ch-2-sect-4">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.basic.summary">
<title>摘要</title>
<para>我们在这一章里学习了许多Subversion的基本概念：</para>
Modified: trunk/src/zh/book/ch03.xml
==============================================================================
--- trunk/src/zh/book/ch03.xml (original)
+++ trunk/src/zh/book/ch03.xml Wed Jan 25 01:01:34 2006
@@ -1,18 +1,18 @@
-<chapter id="svn-ch-3">
+<chapter id="svn.tour">
<title>指导教程</title>
<simplesect>
<para>现在，我们将要深入到Subversion到使用细节当中，完成本章，你将学会所有日常使用的Subversion命令，你将从一个初始化检出开始，做出修改并检查，你也将会学到如何将别人的修改取到工作拷贝，检查他们，并解决所有可能发生的冲突。</para>
- <para>这一章并不是Subversion命令的完全列表—而是你将会遇到的最常用任务的介绍，这一章假定你已经读过并且理解了<xref linkend="svn-ch-2"/>，而且熟悉Subversion的模型，如果想查看所有命令的参考，见<xref linkend="svn-ch-9"/>。</para>
+ <para>这一章并不是Subversion命令的完全列表—而是你将会遇到的最常用任务的介绍，这一章假定你已经读过并且理解了<xref linkend="svn.basic"/>，而且熟悉Subversion的模型，如果想查看所有命令的参考，见<xref linkend="svn.ref"/>。</para>
</simplesect>
<!-- ================================================================= -->
- <!-- ======================== SECTION 1 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-3-sect-1">
+ <!-- ================================================================= -->
+ <sect1 id="svn.tour.help">
<title>帮助！</title>
@@ -22,27 +22,28 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 2 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-3-sect-2">
+ <!-- ================================================================= -->
+ <sect1 id="svn.tour.import">
<title>导入</title>
<para>使用<command>svn import</command>来导入一个新项目到Subversion的版本库，这恐怕是使用Subversion必定要做的第一步操作，但不是经常发生的事情，详细介绍可以看本章后面的<xref
- linkend="svn-ch-3-sect-7.3"/>。</para>
+ linkend="svn.tour.other.import"/>。</para>
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 3 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-3-sect-3">
+ <!-- ================================================================= -->
+ <sect1 id="svn.tour.revs">
<title>修订版本: 号码、关键字和日期，噢，我的！</title>
- <para>在继续之前你一定要知道如何识别版本库的一个修订版本，像你在<xref linkend="svn-ch-2-sect-3.2"/>看到的，一个修订版本就是版本库的一个<quote>快照</quote>，当你的版本库持续扩大，你必须有手段来识别这些快照。</para>
+ <para>在继续之前你一定要知道如何识别版本库的一个修订版本，像你在<xref linkend="svn.basic.in-action.revs"/>看到的，一个修订版本就是版本库的一个<quote>快照</quote>，当你的版本库持续扩大，你必须有手段来识别这些快照。</para>
<para>你可以使用<option>--revision</option>（<option>-r</option>）参数来选择特定修订版本（<command>svn --revision REV</command>），你也可以指定在两个修订版本之间的一个范围 （<command>svn --revision REV1:REV2</command>）。你可以在Subversion中通过修订版本号、关键字或日期指定特定修订版本。</para>
- <sect2 id="svn-ch-3-sect-3.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.revs.numbers">
<title>修订版本号</title>
<para>当你新建了一个Subversion版本库，从修订版本号0开始，每一次成功的提交加1，当你提交成功，Subversion告诉客户端这个新版本号：</para>
@@ -58,7 +59,8 @@
</sect2>
- <sect2 id="svn-ch-3-sect-3.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.revs.keywords">
<title>修订版本关键字</title>
<para>Subversion客户端可以理解一些<firstterm>修订版本关键字</firstterm>，这些关键字可以用来代替<option>--revision</option>的数字参数，这会被Subversion解释到特定版本：</para>
@@ -113,26 +115,27 @@
# shows log message for the latest repository commit
$ svn diff --revision HEAD
-# compares your working file (with local mods) to the latest version
-# in the repository.
+# compares your working file (with local changes) to the latest version
+# in the repository
$ svn diff --revision BASE:HEAD foo.c
-# compares your <quote>pristine</quote> foo.c (no local mods) with the
+# compares your <quote>pristine</quote> foo.c (no local changes) with the
# latest version in the repository
$ svn log --revision BASE:HEAD
# shows all commit logs since you last updated
$ svn update --revision PREV foo.c
-# rewinds the last change on foo.c.
-# (foo.c's working revision is decreased.)
+# rewinds the last change on foo.c
+# (foo.c's working revision is decreased)
</screen>
<para>这些关键字允许你执行许多常用（而且有用）的操作，而不必去查询特定的修订版本号，或者记住本地拷贝的修订版本号。</para>
</sect2>
- <sect2 id="svn-ch-3-sect-3.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.revs.dates">
<title>修订版本日期</title>
<para>在任何你使用特定版本号和版本关键字的地方，你也可以在<quote>{}</quote>中使用日期，你也可通过日期或者版本号配合使用来访问一段时间的修改！</para>
@@ -193,9 +196,9 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 4 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-3-sect-4">
+ <!-- ================================================================= -->
+ <sect1 id="svn.tour.initial">
<title>初始化的Checkout</title>
<para>大多数时候，你会使用<firstterm>checkout</firstterm>从版本库取出一个新拷贝开始使用Subversion，这样会在本机创建一个项目的本地拷贝，这个拷贝包括版本库中的HEAD（最新的）版本：</para>
@@ -213,9 +216,56 @@
</screen>
<sidebar>
- <title>版本库规划</title>
+ <title>What's in a Name?</title>
- <para>你也许会为在每个URL上包括<literal>trunk</literal>感到好奇，我们将在<xref linkend="svn-ch-4"/>详细论述这种推荐的规划方式。</para>
+ <para>Subversion tries hard not to limit the type of data you
+ can place under version control. The contents of files and
+ property values are stored and transmitted as binary data, and
+ the <xref linkend="svn.advanced.props.special.mime-type"/>
+ tells you how to give Subversion a hint that
+ <quote>textual</quote> operations don't make sense for a
+ particular file. There are a few places, however, where
+ Subversion places restrictions on information it
+ stores.</para>
+
+ <para>Subversion handles text internally as UTF-8 encoded
+ Unicode. As a result, certain items which are inherently
+ <quote>textual</quote>, such as property names, path names,
+ and log messages, can only contain legal UTF-8 characters. It
+ also provides a minimum requirement for use of the
+ <literal>svn:mime-type</literal> property—if a file's
+ contents aren't compatible with UTF-8, you should mark it as a
+ binary file. Otherwise, Subversion will attempt to merge
+ differences using UTF-8, which is likely to leave garbage in
+ the file.</para>
+
+ <para>In addition, path names are used as XML attribute values
+ in WebDAV exchanges, as well in as some of Subversion's
+ housekeeping files. This means that path names can only
+ contain legal XML (1.0) characters. Subversion also prohibits
+ TAB, CR, and LF characters in path names, so they aren't
+ broken up in diffs, or in the output of commands like <xref
+ linkend="svn.ref.svn.c.log"/> or <xref
+ linkend="svn.ref.svn.c.status"/>.</para>
+
+ <para>While it may seem like a lot to remember, in practice
+ these limitations are rarely a problem. As long as your
+ locale settings are compatible with UTF-8, and you don't use
+ control characters in path names, you should have no trouble
+ communicating with Subversion. The command-line client adds
+ an extra bit of help—it will automatically escape legal
+ path characters as needed in URLs you type to create
+ <quote>legally correct</quote> versions for internal
+ use.</para>
+
+ <para>Experienced users of Subversion have also developed a set
+ of best-practice conventions for laying out paths in the
+ repository. While these aren't strict requirements like the
+ syntax described above, they help to organize frequently
+ performed tasks. The <literal>/trunk</literal> part of URLs
+ you'll find throughout this book is one of these conventions;
+ we'll talk a lot more about it and related recommendations in
+ <xref linkend="svn.branchmerge"/>.</para>
</sidebar>
@@ -233,7 +283,7 @@
</screen>
<para>因为Subversion使用<quote>拷贝-修改-合并</quote>模型而不是<quote>锁定-修改-解锁</quote>模型（见<xref
- linkend="svn-ch-2"/>），你可以开始修改工作拷贝中的目录和文件，你的工作拷贝和你的系统中的其它文件和目录完全一样，你可以编辑并改变它，移动它，也可以完全的删掉它，把它忘了。</para>
+ linkend="svn.basic"/>），你可以开始修改工作拷贝中的目录和文件，你的工作拷贝和你的系统中的其它文件和目录完全一样，你可以编辑并改变它，移动它，也可以完全的删掉它，把它忘了。</para>
<note>
<para>因为你的工作拷贝<quote>同你的系统上的文件和目录没有什么区别</quote>，如果你希望重新规划工作拷贝，你必须要让Subversion知道，当你希望拷贝或者移动工作拷贝的一个项目时，你应该使用<command>svn copy</command>或者 <command>svn
@@ -268,9 +318,9 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 5 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-3-sect-5">
+ <!-- ================================================================= -->
+ <sect1 id="svn.tour.cycle">
<title>基本的工作周期</title>
<para>Subversion有许多特性、选项和华而不实的高级功能，但日常的工作中你只使用其中的一小部分，有一些只在特殊情况才会使用，在这一节里，我们会介绍许多你在日常工作中常见的命令。</para>
@@ -343,7 +393,8 @@
</listitem>
</itemizedlist>
- <sect2 id="svn-ch-3-sect-5.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.cycle.update">
<title>更新你的工作拷贝</title>
<para>
@@ -408,7 +459,8 @@
</sect2>
- <sect2 id="svn-ch-3-sect-5.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.cycle.edit">
<title>修改你的工作拷贝</title>
<para>现在你可以开始工作并且修改你的工作拷贝了，你很容易决定作出一个修改（或者是一组），像写一个新的特性，修正一个错误等等。这时可以使用的Subversion命令包括<command>svn add</command>、
@@ -495,7 +547,8 @@
</sect2>
- <sect2 id="svn-ch-3-sect-5.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.cycle.examine">
<title>检查你的修改</title>
<para>当你完成修改，你需要提交他们到版本库，但是在此之前，检查一下做过什么修改是个好主意，通过提交前的检查，你可以整理一份精确的日志信息，你也可以发现你不小心修改的文件，给了你一次恢复修改的机会。此外，这是一个审查和仔细察看修改的好机会，你可通过命令<command>svn
@@ -510,7 +563,7 @@
<para>Subversion已经被优化来帮助你完成这个任务，可以在不与版本库通讯的情况下做许多事情，详细来说，对于每一个文件，你的的工作拷贝在<filename>.svn</filename>包含了一个<quote>原始的</quote>拷贝，所以Subversion可以快速的告诉你那些文件修改了，甚至允许你在不与版本库通讯的情况下恢复修改。</para>
- <sect3 id="svn-ch-3-sect-5.3.1">
+ <sect3 id="svn.tour.cycle.examine.status">
<title><command>svn status</command></title>
<para>相对于其他命令，你会更多地使用这个<command>svn status</command>命令。</para>
@@ -528,21 +581,28 @@
status</command>可能返回的状态码（注意，<literal>#</literal>之后的不是<command>svn status</command>打印的）。</para>
<screen>
- L abc.c # svn已经在.svn目录锁定了abc.c
-M bar.c # bar.c的内容已经在本地修改过了
- M baz.c # baz.c属性有修改，但没有内容修改
-X 3rd_party # 这个目录是外部定义的一部分
-? foo.o # svn并没有管理foo.o
-! some_dir # svn管理这个，但它可能丢失或者不完整
-~ qux # 作为file/dir/link进行了版本控制，但类型已经改变
-I .screenrc # svn不管理这个，配置确定要忽略它
-A + moved_dir # 包含历史的添加，历史记录了它的来历
-M + moved_dir/README # 包含历史的添加，并有了本地修改
-D stuff/fish.c # 这个文件预定要删除
-A stuff/loot/bloo.h # 这个文件预定要添加
-C stuff/loot/lump.c # 这个文件在更新时发生冲突
-R xyz.c # 这个文件预定要被替换
- S stuff/squawk # 这个文件已经跳转到了分支
+ L some_dir # svn已经在.svn目录锁定了some_dir
+M bar.c # bar.c的内容已经在本地修改过了
+ M baz.c # baz.c属性有修改，但没有内容修改
+X 3rd_party # 这个目录是外部定义的一部分
+? foo.o # svn并没有管理foo.o
+! some_dir # svn管理这个，但它可能丢失或者不完
+~ qux # 作为file/dir/link进行了版本控制，但类型已经改变
+I .screenrc # svn不管理这个，配置确定要忽略它
+A + moved_dir # 包含历史的添加，历史记录了它的来历
+M + moved_dir/README # 包含历史的添加，并有了本地修改
+D stuff/fish.c # 这个文件预定要删除
+A stuff/loot/bloo.h # 这个文件预定要添加
+C stuff/loot/lump.c # 这个文件在更新时发生冲突
+
+ C stuff/loot/glub.c # 文件在更新时发生属性冲突
+R xyz.c # 这个文件预定要被替换
+ S stuff/squawk # 这个文件已经跳转到了分支
+ K dog.jpg # 文件在本地锁定；有锁定令牌
+ O cat.jpg # 文件在版本库被其他用户锁定
+ B bird.jpg # 文件本地锁定，但锁定发生错误
+ T fish.jpg # 文件本地锁定，但锁定丢失
+
</screen>
<para>在这种格式下，<command>svn status</command>打印五列字符，紧跟一些空格，接着是文件或者目录名。第一列告诉一个文件的状态或它的内容，返回代码解释如下：</para>
@@ -589,7 +649,7 @@
<term><computeroutput>X item</computeroutput></term>
<listitem>
<para>目录没有版本化，但是与Subversion的外部定义关联，关于外部定义，可以看<xref
- linkend="svn-ch-7-sect-3"/>。</para>
+ linkend="svn.advanced.externals"/>。</para>
</listitem>
</varlistentry>
@@ -597,7 +657,7 @@
<term><computeroutput>? item</computeroutput></term>
<listitem>
<para>文件、目录或是符号链<filename>item</filename>不在版本控制之下，你可以通过使用<command>svn
- status</command>的<option>--quiet</option>（<option>-q</option>）参数或父目录的<literal>svn:ignore</literal>属性忽略这个问题，关于忽略文件的使用，见<xref linkend="svn-ch-7-sect-2.3.3" />。</para>
+ status</command>的<option>--quiet</option>（<option>-q</option>）参数或父目录的<literal>svn:ignore</literal>属性忽略这个问题，关于忽略文件的使用，见<xref linkend="svn.advanced.props.special.ignore" />。</para>
</listitem>
</varlistentry>
@@ -620,7 +680,7 @@
<term><computeroutput>I item</computeroutput></term>
<listitem>
<para>文件、目录或是符号链<filename>item</filename>不在版本控制下，Subversion已经配置好了会在<command>svn add</command>、<command>svn import</command>和<command>svn status</command>命令忽略这个文件，关于忽略文件，见<xref
- linkend="svn-ch-7-sect-2.3.3"/>。注意，这个符号只会在使用<command>svn
+ linkend="svn.advanced.props.special.ignore"/>。注意，这个符号只会在使用<command>svn
status</command>的参数<option>--no-ignore</option>时才会出现—否则这个文件会被忽略且不会显示！</para>
</listitem>
</varlistentry>
@@ -628,9 +688,9 @@
</variablelist>
<para>第二列说明文件或目录的属性的状态（更多细节可以看<xref
- linkend="svn-ch-7-sect-2"/>），如果一个<computeroutput>M</computeroutput>出现在第二列，说明属性被修改了，否则显示空白。</para>
+ linkend="svn.advanced.props"/>），如果一个<computeroutput>M</computeroutput>出现在第二列，说明属性被修改了，否则显示空白。</para>
- <para>第三列只显示空白或者<computeroutput>L</computeroutput>，<computeroutput>L</computeroutput>表示Subversion已经在<filename>.svn</filename>工作区域锁定了这个项目，当你的<command>svn
+ <para>第三列只显示空白或者<computeroutput>L</computeroutput>，<computeroutput>L</computeroutput>表示Subversion已经锁定了这个目录的工作区域<filename>.svn</filename>，当你的<command>svn
commit</command>正在运行的时候—也许正在输入log信息，运行<command>svn
status</command>你可以看到<computeroutput>L</computeroutput>标记，如果这时候Subversion并没有运行，可以推测Subversion发生中断并且已经锁定，你必须运行<command>svn cleanup</command>来清除锁定（本节后面将有更多论述）。</para>
@@ -639,6 +699,10 @@
<para>第五列只显示空白或是<computeroutput>S</computeroutput>，表示这个目录或文件已经转到了一个分支下了（使用<command>svn
switch</command>）。</para>
+ <para>第六列显示了锁定的信息，将会在<xref
+ linkend="svn.advanced.locking"/>详细说明。
+ </para>
+
<para>如果你传递一个路径给<command>svn
status</command>，它只给你这个项目的信息：</para>
@@ -681,7 +745,7 @@
</sect3>
- <sect3 id="svn-ch-3-sect-5.3.2">
+ <sect3 id="svn.tour.cycle.examine.diff">
<title><command>svn diff</command></title>
<para>另一种检查修改的方式是<command>svn diff</command>命令，你可以通过不带参数的<command>svn diff</command><emphasis>精确的</emphasis>找出你所做的修改，这会输出统一区别格式：<footnote><para>Subversion使用内置区别引擎，缺省情况下输出为统一区别格式。如果你期望不同的输出格式，你可以使用<option>--diff-cmd</option>指定外置的区别程序，并且通过<option>--extensions</option>传递其他参数，举个例子，察看本地文件<filename>foo.c</filename>的区别，同时忽略空格修改，你可以运行<command>svn diff --diff-cmd /usr/bin/diff
@@ -742,7 +806,7 @@
</sect3>
- <sect3 id="svn-ch-3-sect-5.3.3">
+ <sect3 id="svn.tour.cycle.examine.revert">
<title><command>svn revert</command></title>
<para>假设你通过上面的diff输出发现你不小心用编辑器在<filename>README</filename>中输入了一些字符。
@@ -809,7 +873,8 @@
</sect2>
- <sect2 id="svn-ch-3-sect-5.4">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.cycle.resolve">
<title>解决冲突（合并别人的修改）</title>
<para>我们可以使用<command>svn status -u</command>来预测冲突，当你运行<command>svn
@@ -836,7 +901,7 @@
</listitem>
<listitem>
- <para>如果Subversion认为这个文件是可合并的，它会置入<firstterm>冲突标记</firstterm>—特殊的横线分开冲突的<quote>两面</quote>—在文件里可视化的描述重叠的部分（Subversion使用<literal>svn:mime-type</literal>属性来决定一个文件是否可以使用上下文的，以行为基础合并，更多信息可以看<xref linkend="svn-ch-7-sect-2.3.2"/>）。</para>
+ <para>如果Subversion认为这个文件是可合并的，它会置入<firstterm>冲突标记</firstterm>—特殊的横线分开冲突的<quote>两面</quote>—在文件里可视化的描述重叠的部分（Subversion使用<literal>svn:mime-type</literal>属性来决定一个文件是否可以使用上下文的，以行为基础合并，更多信息可以看<xref linkend="svn.advanced.props.special.mime-type"/>）。</para>
</listitem>
<listitem>
@@ -919,7 +984,7 @@
Resolved conflicted state of 'sandwich.txt'
</screen>
- <sect3 id="svn-ch-3-sect-5.4.1">
+ <sect3 id="svn.tour.cycle.resolve.byhand">
<title>手工合并冲突</title>
<para>第一次尝试解决冲突让人感觉很害怕，但经过一点训练，它简单的像是骑着车子下坡。</para>
@@ -990,7 +1055,7 @@
</sect3>
- <sect3 id="svn-ch-3-sect-5.4.2">
+ <sect3 id="svn.tour.cycle.resolve.copyover">
<title>拷贝覆盖你的工作文件</title>
<para>如果你只是希望取消你的修改，你可以仅仅拷贝Subversion为你生成的文件替换你的工作拷贝：</para>
@@ -1007,7 +1072,7 @@
</sect3>
- <sect3 id="svn-ch-3-sect-5.4.3">
+ <sect3 id="svn.tour.cycle.resolve.revert">
<title>下注：使用<command>svn revert</command></title>
<para>如果你得到冲突，经过检查你决定取消自己的修改并且重新编辑，你可以恢复你的修改：</para>
@@ -1027,7 +1092,7 @@
</sect2>
- <sect2 id="svn-ch-3-sect-5.5">
+ <sect2 id="svn.tour.cycle.commit">
<title>提交你得修改</title>
<para>最后！你的修改结束了，你合并了服务器上所有的修改，你准备好提交修改到版本库。</para>
@@ -1050,7 +1115,7 @@
Committed revision 4.
</screen>
- <para>如果你没有指定<option>--message</option>或者<option>--file</option>选项，Subversion会自动地启动你最喜欢的编辑器（见<xref linkend="svn-ch-7-sect-1.3.2"/>的<literal>editor-cmd</literal>部分）来编辑日志信息。</para>
+ <para>如果你没有指定<option>--message</option>或者<option>--file</option>选项，Subversion会自动地启动你最喜欢的编辑器（见<xref linkend="svn.advanced.confarea.opts.config"/>的<literal>editor-cmd</literal>部分）来编辑日志信息。</para>
<tip>
@@ -1087,9 +1152,9 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 6 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-3-sect-6">
+ <!-- ================================================================= -->
+ <sect1 id="svn.tour.history">
<title>检验历史</title>
<para>我们曾经说过，版本库就像是一台时间机器，它记录了所有提交的修改，允许你检查文件或目录以及相关元数据的历史。通过一个Subversion命令你可以根据时间或修订号取出一个过去的版本（或者恢复现在的工作拷贝），然而，有时候我们只是想<emphasis>看看</emphasis>历史而不想<emphasis>回到</emphasis>历史。</para>
@@ -1101,7 +1166,7 @@
<varlistentry>
<term><command>svn log</command></term>
<listitem>
- <para>展示给你主要信息：附加在版本上的日志信息和所有版本的路径修改。</para>
+ <para>展示给你主要信息：每个版本附加在版本上的作者与日期信息和所有路径修改。</para>
</listitem>
</varlistentry>
@@ -1129,7 +1194,8 @@
</variablelist>
- <sect2 id="svn-ch-3-sect-6.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.history.log">
<title><command>svn log</command></title>
<para>找出一个文件或目录的历史信息，使用<command>svn log</command>命令，<command>svn log</command>将会提供你一条记录，包括：谁对文件或目录作了修改、哪个修订版本作了修改、修订版本的日期和时间、还有如果你当时提供了日志信息，也会显示。</para>
@@ -1188,11 +1254,16 @@
------------------------------------------------------------------------
</screen>
-
+ <para>
+ <command>svn log</command> also takes a <option>--quiet</option>
+ (<option>-q</option>) switch, which suppresses the body of the
+ log message. When combined with <option>--verbose</option>, it
+ gives just the names of the changed files.</para>
+
<sidebar>
<title>为什么<command>svn log</command>给我一个空的回应？</title>
- <para>当使用Subversion一些时间后，许多用户会遇到这种情况：</para>
+ <para>当使用Subversion一些时间后，许多用户会遇到这种情况：</para>
<screen>
$ svn log -r 2
@@ -1207,8 +1278,9 @@
</sect2>
- <sect2 id="svn-ch-3-sect-6.2">
- <title>svn diff</title>
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.history.diff">
+ <title><command>svn diff</command></title>
<para>我们已经看过<command>svn diff</command>—使用标准区别文件格式显示区别，它在提交前用来显示本地工作拷贝与版本库的区别。</para>
@@ -1230,7 +1302,7 @@
</itemizedlist>
- <sect3 id="svn-ch-3-sect-6.2.1">
+ <sect3 id="svn.tour.history.diff.local">
<title>比较本地修改</title>
<para>像我们看到的，不使用任何参数调用时，<command>svn diff</command>将会比较你的工作文件与缓存在<filename>.svn</filename>的<quote>原始</quote>拷贝：</para>
@@ -1253,7 +1325,7 @@
</sect3>
- <sect3 id="svn-ch-3-sect-6.2.2">
+ <sect3 id="svn.tour.history.diff.wcrepos">
<title>比较工作拷贝和版本库</title>
<para>如果传递一个<option>--revision</option>（<option>-r</option>）参数，你的工作拷贝会与指定的版本比较。</para>
@@ -1276,7 +1348,7 @@
</sect3>
- <sect3 id="svn-ch-3-sect-6.2.3">
+ <sect3 id="svn.tour.history.diff.reposrepos">
<title>比较版本库与版本库</title>
<para>如果通过<option>--revision</option>
@@ -1309,7 +1381,8 @@
</sect2>
- <sect2 id="svn-ch-3-sect-6.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.history.cat">
<title><command>svn cat</command></title>
<para>如果你只是希望检查一个过去的版本而不希望察看它们的区别，使用<command>svn cat</command>：</para>
@@ -1338,7 +1411,8 @@
</sect2>
- <sect2 id="svn-ch-3-sect-6.4">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.history.list">
<title><command>svn list</command></title>
<para><command>svn list</command>可以在不下载文件到本地目录的情况下来察看目录中的文件：</para>
@@ -1367,7 +1441,8 @@
</sect2>
- <sect2 id="svn-ch-3-sect-6.5">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.history.finalword">
<title>关于历史的最后一个词</title>
<para>除了以上的命令，你可以使用带参数<option>--revision</option>的<command>svn update</command>和<command>svn
@@ -1386,14 +1461,15 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 7 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-3-sect-7">
+ <!-- ================================================================= -->
+ <sect1 id="svn.tour.other">
<title>其他有用的命令</title>
<para>不象这章前面讨论的那些经常用到的命令，这些命令只是偶尔被用到。</para>
- <sect2 id="svn-ch-3-sect-7.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.other.cleanup">
<title><command>svn cleanup</command></title>
<para>当Subversion改变你的工作拷贝（或是<filename>.svn</filename>中的任何信息），它会尽可能的小心，在修改任何事情之前，它把意图写到日志文件中去，然后执行log文件中的命令，然后删掉日志文件，这与分类帐的文件系统架构类似。如果Subversion的操作中断了（举个例子：进程被杀死了，机器死掉了），日志文件会保存在硬盘上，通过重新执行日志文件，Subversion可以完成上一次开始的操作，你的工作拷贝可以回到一致的状态。</para>
@@ -1413,14 +1489,16 @@
</sect2>
- <sect2 id="svn-ch-3-sect-7.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.tour.other.import">
<title><command>svn import</command></title>
<para><command>svn import</command>命令是拷贝用户的一个未被版本化的目录树到版本库最快的方法，如果需要，它也要建立一些中介文件。</para>
<screen>
$ svnadmin create /usr/local/svn/newrepos
-$ svn import mytree file:///usr/local/svn/newrepos/some/project
+$ svn import mytree file:///usr/local/svn/newrepos/some/project \
+ -m "Initial import"
Adding mytree/foo.c
Adding mytree/bar.c
Adding mytree/subdir
@@ -1446,12 +1524,12 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 8 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-3-sect-8">
+ <!-- ================================================================= -->
+ <sect1 id="svn.tour.summary">
<title>摘要</title>
- <para>我们已经覆盖了大多数Subversion的客户端命令，引人注目的例外是处理分支与合并（见<xref linkend="svn-ch-4"/>）以及属性（见<xref linkend="svn-ch-7-sect-2"/>）的命令，然而你也许会希望跳到<xref linkend="svn-ch-9"/>来察看所有不同的命令—怎样利用它们使你的工作更容易。</para>
+ <para>我们已经覆盖了大多数Subversion的客户端命令，引人注目的例外是处理分支与合并（见<xref linkend="svn.branchmerge"/>）以及属性（见<xref linkend="svn-ch-7-sect-2"/>）的命令，然而你也许会希望跳到<xref linkend="svn.ref"/>来察看所有不同的命令—怎样利用它们使你的工作更容易。</para>
</sect1>
Modified: trunk/src/zh/book/ch04.xml
==============================================================================
--- trunk/src/zh/book/ch04.xml (original)
+++ trunk/src/zh/book/ch04.xml Wed Jan 25 01:01:34 2006
@@ -1,18 +1,18 @@
-<chapter id="svn-ch-4">
+<chapter id="svn.branchmerge">
<title>分支与合并</title>
<simplesect>
<para>分支、标签和合并是所有版本控制系统的共同概念，如果你并不熟悉这些概念，我们会在这一章里很好的介绍，如果你很熟悉，非常希望你有兴趣知道Subversion是怎样实现这些概念的。</para>
- <para>分支是版本控制的基础组成部分，如果你允许Subversion来管理你的数据，这个特性将是你所必须依赖的 ，这一章假定你已经熟悉了Subversion的基本概念（<xref linkend="svn-ch-2"/>）。</para>
+ <para>分支是版本控制的基础组成部分，如果你允许Subversion来管理你的数据，这个特性将是你所必须依赖的 ，这一章假定你已经熟悉了Subversion的基本概念（<xref linkend="svn.basic"/>）。</para>
</simplesect>
<!-- ================================================================= -->
- <!-- ======================== SECTION 1 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-4-sect-1">
+ <!-- ================================================================= -->
+ <sect1 id="svn.branchmerge.whatis">
<title>什么是分支？</title>
<para>假设你的工作是维护本公司一个部门的手册文档，一天，另一个部门问你要相同的手册，但一些地方会有<quote>区别</quote>，因为他们有不同的需要。</para>
@@ -21,9 +21,9 @@
<para>你也许希望在两个版本同时作修改，举个例子，你在第一个版本发现了一个拼写错误，很显然这个错误也会出现在第二个版本里。两份文档几乎相同，毕竟，只有许多特定的微小区别。</para>
- <para>这是<firstterm>分支</firstterm>的基本概念—正如它的名字，开发的一条线独立于另一条线，如果回顾历史，可以发现两条线分享共同的历史，一个分支总是从一个备份开始的，从那里开始，发展自己独有的历史（见 <xref linkend="svn-ch-4-dia-1"/>）。</para>
+ <para>这是<firstterm>分支</firstterm>的基本概念—正如它的名字，开发的一条线独立于另一条线，如果回顾历史，可以发现两条线分享共同的历史，一个分支总是从一个备份开始的，从那里开始，发展自己独有的历史（见 <xref linkend="svn.branchmerge.whatis.dia-1"/>）。</para>
- <figure id="svn-ch-4-dia-1">
+ <figure id="svn.branchmerge.whatis.dia-1">
<title>分支开发</title>
<graphic fileref="images/ch04dia1.png"/>
</figure>
@@ -33,16 +33,16 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 2 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-4-sect-2">
+ <!-- ================================================================= -->
+ <sect1 id="svn.branchmerge.using">
<title>使用分支</title>
- <para>在这一点上，你必须理解每一次提交是怎样建立整个新的文件系统树（叫做<quote>修订版本</quote>）的，如果没有，可以回头去读<xref linkend="svn-ch-2-sect-3.2"/>。</para>
+ <para>在这一点上，你必须理解每一次提交是怎样建立整个新的文件系统树（叫做<quote>修订版本</quote>）的，如果没有，可以回头去读<xref linkend="svn.basic.in-action.revs"/>。</para>
- <para>对于本章节，我们会回到第2章的同一个例子，还记得你和你的合作者Sally分享一个包含两个项目的版本库，<filename>paint</filename>和<filename>calc</filename>。注意<xref linkend="svn-ch-4-dia-2"/>，然而，现在每个项目的都有一个<filename>trunk</filename>和<filename>branches</filename>子目录，它们存在的理由很快就会清晰起来。</para>
+ <para>对于本章节，我们会回到第2章的同一个例子，还记得你和你的合作者Sally分享一个包含两个项目的版本库，<filename>paint</filename>和<filename>calc</filename>。注意<xref linkend="svn.branchmerge.using.dia-1"/>，然而，现在每个项目的都有一个<filename>trunk</filename>和<filename>branches</filename>子目录，它们存在的理由很快就会清晰起来。</para>
- <figure id="svn-ch-4-dia-2">
+ <figure id="svn.branchmerge.using.dia-1">
<title>开始规划版本库</title>
<graphic fileref="images/ch04dia2.png"/>
</figure>
@@ -55,7 +55,8 @@
<para>最佳方案是创建你自己的分支，或者是版本库的开发线。这允许你保存破坏了一半的工作而不打扰别人，尽管你仍可以选择性的同你的合作者分享信息，你将会看到这是怎样工作的。</para>
- <sect2 id="svn-ch-4-sect-2.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.using.create">
<title>创建分支</title>
<para>建立分支非常的简单—使用<command>svn copy</command>命令给你的工程做个拷贝，Subversion不仅可以拷贝单个文件，也可以拷贝整个目录，在目前情况下，你希望作<filename>/calc/trunk</filename>的拷贝，新的拷贝应该在哪里？在你希望的任何地方—它只是在于项目的政策，我们假设你们项目的政策是在<filename>/calc/branches</filename>建立分支，并且你希望把你的分支叫做<literal>my-calc-branch</literal>，你希望建立一个新的目录<filename>/calc/branches/my-calc-branch</filename>，作为/calc/trunk的拷贝开始它的生命周期。</para>
@@ -101,12 +102,12 @@
</screen>
<para>其实这两种方法没有什么区别，两个过程都在版本341建立了一个新目录作为<filename>/calc/trunk</filename>的一个备份，这些可以在<xref
- linkend="svn-ch-4-dia-3"/>看到，注意第二种方法，只是执行了一个<emphasis>立即</emphasis>提交。 <footnote>
+ linkend="svn.branchmerge.using.create.dia-1"/>看到，注意第二种方法，只是执行了一个<emphasis>立即</emphasis>提交。 <footnote>
<para>Subversion不支持跨版本库的拷贝，当使用<command>svn
copy</command>或者<command>svn move</command>直接操作URL时你只能在同一个版本库内操作。</para>
</footnote>这是一个简单的过程，因为你不需要取出版本库一个庞大的镜像，事实上，这个技术不需要你有工作拷贝。</para>
- <figure id="svn-ch-4-dia-3">
+ <figure id="svn.branchmerge.using.create.dia-1">
<title>拷贝后的版本库</title>
<graphic fileref="images/ch04dia3.png"/>
</figure>
@@ -123,7 +124,8 @@
</sect2>
- <sect2 id="svn-ch-4-sect-2.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.using.work">
<title>在分支上工作</title>
<para>现在你已经在项目里建立分支了，你可以取出一个新的工作拷贝来开始使用：</para>
@@ -137,7 +139,7 @@
</screen>
<para>这一份工作拷贝没有什么特别的，它只是版本库另一个目录的一个镜像罢了，当你提交修改时，Sally在更新时不会看到改变，她是<filename>/calc/trunk</filename>的工作拷贝。（确定要读本章后面的<xref
- linkend="svn-ch-4-sect-5"/>，<command>svn switch</command>命令是建立分支工作拷贝的另一个选择。）</para>
+ linkend="svn.branchmerge.switchwc"/>，<command>svn switch</command>命令是建立分支工作拷贝的另一个选择。）</para>
<para>我们假定本周就要过去了，如下的提交发生：</para>
@@ -157,9 +159,9 @@
</listitem>
</itemizedlist>
- <para>现在有两个独立开发线，<xref linkend="svn-ch-4-dia-4"/>显示了<filename>integer.c</filename>的历史。</para>
+ <para>现在有两个独立开发线，<xref linkend="svn.branchmerge.using.work.dia-1"/>显示了<filename>integer.c</filename>的历史。</para>
- <figure id="svn-ch-4-dia-4">
+ <figure id="svn.branchmerge.using.work.dia-1">
<title>一个文件的分支历史</title>
<graphic fileref="images/ch04dia4.png"/>
</figure>
@@ -237,7 +239,8 @@
</sect2>
- <sect2 id="svn-ch-4-sect-2.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.using.concepts">
<title>分支背后的关键概念</title>
<para>在这个章节你需要记住两个重要的经验。
@@ -257,9 +260,9 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 3 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-4-sect-3">
+ <!-- ================================================================= -->
+ <sect1 id="svn.branchmerge.copychanges">
<title>在分支间拷贝修改</title>
<para>现在你与Sally在同一个项目的并行分支上工作：你在私有分支上，而Sally在主干（<firstterm>trunk</firstterm>）或者叫做开发主线上。</para>
@@ -271,7 +274,8 @@
<para>相反，在你工作的时候你和Sally仍然可以继续分享修改，这依赖于你决定什么值得分享，Subversion给你在分支间选择性<quote>拷贝</quote>修改的能力，当你完成了分支上的所有工作，所有的分支修改可以被拷贝回到主干。</para>
- <sect2 id="svn-ch-4-sect-3.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.copychanges.specific">
<title>拷贝特定的修改</title>
@@ -287,14 +291,14 @@
--- integer.c (revision 343)
+++ integer.c (revision 344)
@@ -147,7 +147,7 @@
- case 6: sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break;
- case 7: sprintf(info->operating_system, "Macintosh"); break;
- case 8: sprintf(info->operating_system, "Z-System"); break;
-- case 9: sprintf(info->operating_system, "CPM"); break;
-+ case 9: sprintf(info->operating_system, "CP/M"); break;
- case 10: sprintf(info->operating_system, "TOPS-20"); break;
- case 11: sprintf(info->operating_system, "NTFS (Windows NT)"); break;
- case 12: sprintf(info->operating_system, "QDOS"); break;
+ case 6: sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break;
+ case 7: sprintf(info->operating_system, "Macintosh"); break;
+ case 8: sprintf(info->operating_system, "Z-System"); break;
+- case 9: sprintf(info->operating_system, "CPM"); break;
++ case 9: sprintf(info->operating_system, "CP/M"); break;
+ case 10: sprintf(info->operating_system, "TOPS-20"); break;
+ case 11: sprintf(info->operating_system, "NTFS (Windows NT)"); break;
+ case 12: sprintf(info->operating_system, "QDOS"); break;
@@ -164,7 +164,7 @@
low = (unsigned short) read_byte(gzfile); /* read LSB */
high = (unsigned short) read_byte(gzfile); /* read MSB */
@@ -302,19 +306,19 @@
- total = low + high; /* add them togethe for correct total */
+ total = low + high; /* add them together for correct total */
- info->extra_header = (unsigned char *) my_malloc(total);
- fread(info->extra_header, total, 1, gzfile);
+ info->extra_header = (unsigned char *) my_malloc(total);
+ fread(info->extra_header, total, 1, gzfile);
@@ -241,7 +241,7 @@
Store the offset with ftell() ! */
- if ((info->data_offset = ftell(gzfile))== -1) {
+ if ((info->data_offset = ftell(gzfile))== -1) {
- printf("error: ftell() retturned -1.\n");
+ printf("error: ftell() returned -1.\n");
exit(1);
}
@@ -249,7 +249,7 @@
- printf("I believe start of compressed data is %u\n", info->data_offset);
+ printf("I believe start of compressed data is %u\n", info->data_offset);
#endif
- /* Set postion eight bytes from the end of the file. */
@@ -368,9 +372,9 @@
</screen>
<para>在这种情况下，确实没有区别，但是<command>svn merge</command>有超越<command>patch</command>的特别能力，使用<command>patch</command>对文件格式有一定的限制，它只能针对文件内容，没有方法表现<emphasis>目录树</emphasis>的修改，例如添加、删除或是改名。如果Sally的修改包括增加一个新的目录，<command>svn diff</command>不会注意到这些，<command>svn diff</command>只会输出有限的补丁格式，所以有些问题无法表达。<footnote>
- <para>在将来，Subversion项目将会计划（或者发明）一种扩展补丁格式来描述目录树改变。</para>
+ <para>在将来，Subversion项目将会计划（或者发明）一种扩展补丁格式来描述目录树的结构和属性变化。</para>
</footnote>
- 但是<command>svn merge</command>命令会通过直接作用你的工作拷贝来表示目录树的修改。</para>
+ 但是<command>svn merge</command>命令会通过直接作用你的工作拷贝来表示目录树的结构和属性变化。</para>
</sidebar>
@@ -397,7 +401,8 @@
</sect2>
- <sect2 id="svn-ch-4-sect-3.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.copychanges.keyconcept">
<title>合并背后的关键概念</title>
<para>你已经看到了<command>svn merge</command>命令的例子，你将会看到更多，如果你对合并是如何工作的感到迷惑，这并不奇怪，很多人和你一样。许多新用户（特别是对版本控制很陌生的用户）会对这个命令的正确语法感到不知所措，不知道怎样和什么时候使用这个特性，不要害怕，这个命令实际上比你想象的简单！有一个简单的技巧来帮助你理解<command>svn merge</command>的行为。</para>
@@ -438,10 +443,11 @@
</sect2>
- <sect2 id="svn-ch-4-sect-3.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.copychanges.bestprac">
<title>合并的最佳实践</title>
- <sect3 id="svn-ch-4-sect-3.3.1">
+ <sect3 id="svn.branchmerge.copychanges.bestprac.track">
<title>手工追踪合并</title>
<para>合并修改听起来很简单，但是实践起来会是很头痛的事，如果你重复合并两个分支，你也许会合并<emphasis>两次</emphasis>同样的修改。当这种事情发生时，有时候事情会依然正常，当对文件打补丁时，Subversion如果注意到这个文件已经有了相应的修改，而不会作任何操作，但是如果已经应用的修改又被修改了，你会得到冲突。</para>
@@ -456,7 +462,7 @@
</sect3>
- <sect3 id="svn-ch-4-sect-3.3.2">
+ <sect3 id="svn.branchmerge.copychanges.bestprac.preview">
<title>预览合并</title>
<para>因为合并只是导致本地修改，它不是一个高风险的操作，如果你在第一次操作错误，你可以运行<command>svn
@@ -483,10 +489,10 @@
<para>每一个人对于<quote>修改集</quote>的概念都有些不一样，至少对于版本控制系统的<quote>修改集特性</quote>这一概念有着不同的期望，根据我们的用途，可以说修改集只是一个有唯一名字的一系列修改集合，修改也许包括文件内容的修改，目录树结构的修改，或是元数据的调整，更通常的说法，一个修改集就是我们可以引用的有名字的补丁。</para>
- <para>在Subversion里，一个全局的修订版本号N标示一个版本库中的树：它代表版本库在N次提交后的样子，它也是一个修改集的隐含名称：如果你比较树N与树N-1，你可以得到你提交的补丁。出于这个原因，想象<quote>版本N</quote>并不只是一棵树，也是一个修改集。如果你使用一个问题追踪工具来管理bug，你可以使用版本号来表示特定的补丁修正了bug—举个例子，<quote>这个问题是在版本9238修正的</quote>，然后其他人可以运行<command>svn log -r9238</command>来查看修正这个bug的修改集，或者使用<command>svn diff -r9237:9238</command>来看补丁本身。Subversion合并命令也使用版本号作为参数，可以将特定修改集从一个分支合到另一个分支：<command>svn merge -r9237:9238</command>将会合并修改集#9238到本地拷贝。</para>
+ <para>在Subversion里，一个全局的修订版本号N标示一个版本库中的树：它代表版本库在N次提交后的样子，它也是一个修改集的隐含名称：如果你比较树N与树N-1，你可以得到你提交的补丁。出于这个原因，想象<quote>版本N</quote>并不只是一棵树，也是一个修改集。如果你使用一个问题追踪工具来管理bug，你可以使用版本号来表示特定的补丁修正了bug—举个例子，<quote>这个问题是在版本9238修正的</quote>，然后其他人可以运行<command>svn log -r9238</command>来查看修正这个bug的修改集，或者使用<command>svn diff -r9237:9238</command>来看补丁本身。Subversion的<literal>合并</literal>命令也使用版本号作为参数，可以将特定修改集从一个分支合到另一个分支：<command>svn merge -r9237:9238</command>将会合并修改集#9238到本地拷贝。</para>
</sidebar>
- <sect3 id="svn-ch-4-sect-3.3.3">
+ <sect3 id="svn.branchmerge.copychanges.bestprac.merge">
<title>合并冲突</title>
<para>就像<command>svn update</command>命令，<command>svn merge</command>会把修改应用到工作拷贝，因此它也会造成冲突，因为<command>svn
@@ -511,23 +517,28 @@
<para>也应当注意前一个例子显示<filename>glorb.h</filename>发生了冲突，我们已经规定本地拷贝没有修改：冲突怎么会发生呢？因为用户可以使用<command>svn merge</command>将过去的任何变化应用到当前工作拷贝，变化包含的文本修改也许并不能干净的应用到工作拷贝文件，即使这些文件没有本地修改。</para>
- <para>另一个<command>svn update</command>和<command>svn merge</command>的小区别是冲突产生的文件的名字不同，在<xref linkend="svn-ch-3-sect-5.4"/>，我们看到过更新产生的文件名字为<filename>filename.mine</filename>、<filename>filename.rOLDREV</filename>和<filename>filename.rNEWREV</filename>，当<command>svn merge</command>产生冲突时，它产生的三个文件分别为 <filename>filename.working</filename>、<filename>filename.left</filename>和<filename>filename.right</filename>。在这种情况下，术语<quote>left</quote>和<quote>right</quote>表示了两棵树比较时的两边，在两种情况下，不同的名字会帮助你区分冲突是因为更新造成的还是合并造成的。</para>
+ <para>另一个<command>svn update</command>和<command>svn merge</command>的小区别是冲突产生的文件的名字不同，在<xref linkend="svn.tour.cycle.resolve"/>，我们看到过更新产生的文件名字为<filename>filename.mine</filename>、<filename>filename.rOLDREV</filename>和<filename>filename.rNEWREV</filename>，当<command>svn merge</command>产生冲突时，它产生的三个文件分别为 <filename>filename.working</filename>、<filename>filename.left</filename>和<filename>filename.right</filename>。在这种情况下，术语<quote>left</quote>和<quote>right</quote>表示了两棵树比较时的两边，在两种情况下，不同的名字会帮助你区分冲突是因为更新造成的还是合并造成的。</para>
</sect3>
- <sect3 id="svn-ch-4-sect-3.3.4">
+ <sect3 id="svn.branchmerge.copychanges.bestprac.ancestry">
<title>关注还是忽视祖先</title>
<para>当与Subversion开发者交谈时你一定会听到提及术语<firstterm>祖先</firstterm>，这个词是用来描述两个对象的关系：如果他们互相关联，一个对象就是另一个的祖先，或者相反。</para>
<para>举个例子，假设你提交版本100，包括对<filename>foo.c</filename>的修改，则foo.c at 99是foo.c at 100的一个<quote>祖先</quote>，另一方面，假设你在版本101删除这个文件，而在102版本提交一个同名的文件，在这个情况下，<filename>foo.c at 99</filename>与<filename>foo.c at 102</filename>看起来是关联的（有同样的路径），但是事实上他们是完全不同的对象，它们并不共享同一个历史或者说<quote>祖先</quote>。</para>
- <para>指出<command>svn diff</command>和<command>svn merge</command>区别的重要性在于，前一个命令忽略祖先，如果你询问<command>svn diff</command>来比较文件<filename>foo.c</filename>的版本99和102，你会看到行为基础的区别，区别命令只是盲目的比较两条路径，但是如果你使用<command>svn merge</command>是比较同样的两个对象，它会注意到他们是不关联的，而且首先尝试删除旧文件，然后添加新文件，你会看到<literal>A foo.c</literal>后面紧跟<literal>D foo.c</literal>。</para>
+ <para>指出<command>svn diff</command>和<command>svn merge</command>区别的重要性在于，前一个命令忽略祖先，如果你询问<command>svn diff</command>来比较文件<filename>foo.c</filename>的版本99和102，你会看到行为基础的区别，<literal>diff</literal>命令只是盲目的比较两条路径，但是如果你使用<command>svn merge</command>是比较同样的两个对象，它会注意到他们是不关联的，而且首先尝试删除旧文件，然后添加新文件，输出会是一个删除紧接着一个增加：</para>
+
+ <screen>
+D foo.c
+A foo.c
+</screen>
- <para>大多数合并包括比较包括祖先关联的两条树，因此<command>svn merge</command>这样运作，然而，你也许会希望合并命令能够比较两个不相关的目录树，举个例子，你有两个目录树分别代表了卖主软件项目的不同版本（见<xref linkend="svn-ch-7-sect-4"/>），如果你使用<command>svn merge</command>进行比较，你会看到第一个目录树被删除，而第二个树添加上！</para>
+ <para>大多数合并包括比较包括祖先关联的两条树，因此<command>svn merge</command>这样运作，然而，你也许会希望<literal>merge</literal>命令能够比较两个不相关的目录树，举个例子，你有两个目录树分别代表了卖主软件项目的不同版本（见<xref linkend="svn.advanced.vendorbr"/>），如果你使用<command>svn merge</command>进行比较，你会看到第一个目录树被删除，而第二个树添加上！</para>
<para>在这个情况下，你只是希望<command>svn merge</command>能够做一个以路径为基础的比较，忽略所有文件和目录的关系，增加<option>--ignore-ancestry</option>选项会导致命令象<command>svn
- diff</command>一样。（相应的，<option>--notice-ancestry</option>选项会使<command>svn diff</command>象合并命令一样行事。）</para>
+ diff</command>一样。（相应的，<option>--notice-ancestry</option>选项会使<command>svn diff</command>象<literal>merge</literal>命令一样行事。）</para>
</sect3>
@@ -537,15 +548,16 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 4 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-4-sect-4">
+ <!-- ================================================================= -->
+ <sect1 id="svn.branchmerge.commonuses">
<title>常见用例</title>
<para>分支和<command>svn
merge</command>有很多不同的用法，这个小节描述了最常见的用法。</para>
- <sect2 id="svn-ch-4-sect-4.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.commonuses.wholebr">
<title>合并一条分支到另一支</title>
<para>为了完成这个例子，我们将时间往前推进，假定已经过了几天，在主干和你的分支上都有许多更改，假定你完成了分支上的工作，已经完成了特性或bug修正，你想合并所有分支的修改到主干上，让别人也可以使用。</para>
@@ -607,7 +619,7 @@
<para>再次说明，日志信息中详细描述了合并到主干的的修改范围，记住一定要这么做，这是你以后需要的重要信息。</para>
- <para>举个例子，你希望在分支上继续工作一周，来进一步加强你的修正，这时版本库的<literal>HEAD</literal>版本是480，你准备好了另一次合并，但是我们在<xref linkend="svn-ch-4-sect-3.3"/>提到过，你不想合并已经合并的内容，你只想合并新的东西，技巧就是指出什么是<quote>新</quote>的。</para>
+ <para>举个例子，你希望在分支上继续工作一周，来进一步加强你的修正，这时版本库的<literal>HEAD</literal>版本是480，你准备好了另一次合并，但是我们在<xref linkend="svn.branchmerge.copychanges.bestprac"/>提到过，你不想合并已经合并的内容，你只想合并新的东西，技巧就是指出什么是<quote>新</quote>的。</para>
<para>第一步是在主干上运行<command>svn log</command>察看最后一次与分支合并的日志信息：</para>
@@ -649,7 +661,8 @@
</sect2>
- <sect2 id="svn-ch-4-sect-4.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.commonuses.undo">
<title>取消修改</title>
<para><command>svn merge</command>另一个常用的做法是取消已经做得提交，假设你愉快的在<filename>/calc/trunk</filename>工作，你发现303版本对<filename>integer.c</filename>的修改完全错了，它不应该被提交，你可以使用<command>svn
@@ -684,13 +697,14 @@
<para>是的，这是对的。当我们说<quote>删除</quote>一个修改时，我们只是说从<literal>HEAD</literal>删除，原始的修改还保存在版本库历史中，在多数情况下，这是足够好的。大多数人只是对追踪<literal>HEAD</literal>版本感兴趣，在一些特定情况下，你也许希望毁掉所有提交的证据（或许某个人提交了一个秘密文件），这不是很容易的，因为Subversion设计用来不丢失任何信息，每个修订版本都是不可变的目录树 ，从历史删除一个版本会导致多米诺效应，会在后面的版本导致混乱甚至会影响所有的工作拷贝。
<footnote>
- <para>Subversion项目有计划，不管用什么方式，总有一天要实现<command>svnadmin obliterate</command>命令来进行永久删除操作，而此时可以看<xref linkend="svn-ch-5-sect-3.1.3"/>。</para>
+ <para>Subversion项目有计划，不管用什么方式，总有一天要实现<command>svnadmin obliterate</command>命令来进行永久删除操作，而此时可以看<xref linkend="svn.reposadmin.maint.tk.svndumpfilter"/>。</para>
</footnote>
</para>
</sect2>
- <sect2 id="svn-ch-4-sect-4.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.commonuses.resurrect">
<title>找回删除的项目</title>
<para>版本控制系统非常重要的一个特性就是它的信息从不丢失，即使当你删除了文件或目录，它也许从HEAD版本消失了 ，但这个对象依然存在于历史的早期版本 ，一个新手经常问到的问题是<quote>怎样找回我的文件和目录？</quote></para>
@@ -723,7 +737,7 @@
<para>以上是最重要的部分—重新找到你需要恢复的对象。现在你已经知道该恢复的文件，而你有两种选择。</para>
<para>一种是对版本反向使用<command>svn merge</command>到808（我们已经学会了如何取消修改，见<xref
- linkend="svn-ch-4-sect-4.2"/>），这样会重新添加<filename>real.c</filename>，这个文件会列入增加的计划，经过一次提交，这个文件重新回到<literal>HEAD</literal>。</para>
+ linkend="svn.branchmerge.commonuses.undo"/>），这样会重新添加<filename>real.c</filename>，这个文件会列入增加的计划，经过一次提交，这个文件重新回到<literal>HEAD</literal>。</para>
<para>在这个例子里，这不是一个好的策略，这样做不仅把<filename>real.c</filename>加入添加到计划，也取消了对<filename>integer.c</filename>的修改，而这不是你期望的。确实，你可以恢复到版本808，然后对<filename>integer.c</filename>执行取消<command>svn revert</command>操作，但这样的操作无法扩大使用，因为如果从版本808修改了90个文件怎么办？</para>
@@ -748,12 +762,13 @@
</sect2>
- <sect2 id="svn-ch-4-sect-4.4">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.commonuses.patterns">
<title>常用分支模式</title>
<para>版本控制在软件开发中广泛使用，这里是团队里程序员最常用的两种分支/合并模式的介绍，如果你不是使用Subversion软件开发，可随意跳过本小节，如果你是第一次使用版本控制的软件开发者，请更加注意，以下模式被许多老兵当作最佳实践，这个过程并不只是针对Subversion，在任何版本控制系统中都一样，但是在这里使用Subversion术语会感觉更方便一点。</para>
- <sect3 id="svn-ch-4-sect-4.4.1">
+ <sect3 id="svn.branchmerge.commonuses.patterns.release">
<title>发布分支</title>
<para>大多数软件存在这样一个生命周期：编码、测试、发布，然后重复。这样有两个问题，第一，开发者需要在质量保证小组测试假定稳定版本时继续开发新特性，新工作在软件测试时不可以中断，第二，小组必须一直支持老的发布版本和软件；如果一个bug在最新的代码中发现，它一定也存在已发布的版本中，客户希望立刻得到错误修正而不必等到新版本发布。</para>
@@ -792,7 +807,7 @@
</sect3>
- <sect3 id="svn-ch-4-sect-4.4.2">
+ <sect3 id="svn.branchmerge.commonuses.patterns.feature">
<title>特性分支</title>
<para>一个<firstterm>特性分支</firstterm>是本章中那个重要例子中的分支，你正在那个分支上工作，而Sally还在<filename>/trunk</filename>继续工作，这是一个临时分支，用来作复杂的修改而不会干扰<filename>/trunk</filename>的稳定性，不象发布分支（也许要永远支持），特性分支出生，使用了一段时间，合并到主干，然后最终被删除掉，它们在有限的时间里有用。</para>
@@ -803,7 +818,7 @@
<para>最终，有一个问题就是怎样保持一个特性分支<quote>同步</quote>于工作中的主干，在前面提到过，在一个分支上工作数周或几个月是很有风险的，主干的修改也许会持续涌入，因为这一点，两条线的开发会区别巨大，合并分支回到主干会成为一个噩梦。</para>
- <para>这种情况最好通过有规律的将主干合并到分支来避免，制定这样一个政策：每周将上周的修改合并到分支，注意这样做时需要小心，需要手工记录合并的过程，以避免重复的合并（在<xref linkend="svn-ch-4-sect-3.3.1"/>描述过），你需要小心的撰写合并的日志信息，精确的描述合并包括的范围（在<xref linkend="svn-ch-4-sect-4.1"/>中描述过），这看起来像是胁迫，可是实际上是容易做到的。</para>
+ <para>这种情况最好通过有规律的将主干合并到分支来避免，制定这样一个政策：每周将上周的修改合并到分支，注意这样做时需要小心，需要手工记录合并的过程，以避免重复的合并（在<xref linkend="svn.branchmerge.copychanges.bestprac.track"/>描述过），你需要小心的撰写合并的日志信息，精确的描述合并包括的范围（在<xref linkend="svn.branchmerge.commonuses.wholebr"/>中描述过），这看起来像是胁迫，可是实际上是容易做到的。</para>
<para>在一些时候，你已经准备好了将<quote>同步的</quote>特性分支合并回到主干，为此，开始做一次将主干最新修改和分支的最终合并，这样以后，除了你的分支修改的部分，最新的分支和主干将会绝对一致，所以在这个特别的例子里，你会通过直接比较分支和主干来进行合并：</para>
@@ -834,9 +849,9 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 5 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-4-sect-5">
+ <!-- ================================================================= -->
+ <sect1 id="svn.branchmerge.switchwc">
<title>转换工作拷贝</title>
<para><command>svn switch</command>命令改变存在的工作拷贝到另一个分支，然而这个命令在分支上工作时不是严格必要的，它只是提供了一个快捷方式。在前面的例子里，完成了私有分支的建立，你取出了新目录的工作拷贝，相反，你可以简单的告诉Subversion改变你的<filename>/calc/trunk</filename>的工作拷贝到分支的路径：</para>
@@ -877,14 +892,14 @@
<para>如果你的工作拷贝包含许多来自不同版本库目录跳转的子树，它会工作如常。当你更新时，你会得到每一个目录适当的补丁，当你提交时，你的本地修改会一直作为一个单独的原子修改提交到版本库。</para>
<para>注意，因为你的工作拷贝可以在混合位置的情况下工作正常，但是所有的位置必须在同一个版本库，Subversion的版本库不能互相通信，这个特性还不在Subversion 1.0的计划里。<footnote><para>当你的服务器位置改变，而你不想放弃存在的本地拷贝，你<emphasis>可以</emphasis>使用带选项<option>--relocate</option>的<command>svn switch</command>命令转换URL，见<xref
- linkend="svn-ch-9"/>的<command>svn switch</command>查看更多信息和例子。</para>
+ linkend="svn.ref"/>的<command>svn switch</command>查看更多信息和例子。</para>
</footnote></para>
<sidebar>
<title>跳转和更新</title>
<para>你注意到<command>svn
- switch</command>和<command>svn update</command>的输出很像？switch命令只是update命令的一个超集。</para>
+ switch</command>和<command>svn update</command>的输出很像？<literal>switch</literal>命令只是update命令的一个超集。</para>
<para>当你运行<command>svn update</command>时，你会告诉版本库比较两个目录树，版本库这样做，并且返回给客户区别的描述，<command>svn
switch</command>和<command>svn update</command>两个命令唯一区别就是<command>svn update</command>会一直比较同一路径。</para>
@@ -904,16 +919,17 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 6 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-4-sect-6">
+ <!-- ================================================================= -->
+ <sect1 id="svn.branchmerge.tags">
<title>标签</title>
- <para>另一个常见的版本控制系统概念是标签（<firstterm>tag</firstterm>），一个标签只是一个项目某一时间的<quote>快照</quote>，在Subversion里这个概念无处不在—每一次提交的修订版本都是一个精确的快照。</para>
+ <para>另一个常见的版本控制系统概念是标¾（<firstterm>tag</firstterm>），一个标签只是一个项目某一时间的<quote>快照</quote>，在Subversion里这个概念无处不在—每一次提交的修订版本都是一个精确的快照。</para>
<para>然而人们希望更人性化的标签名称，像<literal>release-1.0</literal>。他们也希望可以对一个子目录快照，毕竟，记住release-1.0是修订版本4822的某一小部分不是件很容易的事。</para>
- <sect2 id="svn-ch-4-sect-6.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.tags.mksimple">
<title>建立最简单的标签</title>
<para><command>svn copy</command>再次登场，你希望建立一个<filename>/calc/trunk</filename>的一个快照，就像<literal>HEAD</literal>修订版本，建立这样一个拷贝：</para>
@@ -926,15 +942,16 @@
Committed revision 351.
</screen>
- <para>这个例子假定<filename>/calc/tags</filename>目录已经存在（如果不是，见<xref linkend="svn-ch-9-sect-1.2-re-mkdir"/>），拷贝完成之后，一个表示当时<literal>HEAD</literal>版本的/calc/trunk目录的镜像已经永久的拷贝到<filename>release-1.0</filename>目录。当然，你会希望更精确一点，以防其他人在你不注意的时候提交修改，所以，如果你知道<filename>/calc/trunk</filename>的版本350是你想要的快照，你可以使用<command>svn copy</command>加参数 <option>-r 350</option>。</para>
+ <para>这个例子假定<filename>/calc/tags</filename>目录已经存在（如果不是，见<xref linkend="svn.ref.svn.c.mkdir"/>），拷贝完成之后，一个表示当时<literal>HEAD</literal>版本的/calc/trunk目录的镜像已经永久的拷贝到<filename>release-1.0</filename>目录。当然，你会希望更精确一点，以防其他人在你不注意的时候提交修改，所以，如果你知道<filename>/calc/trunk</filename>的版本350是你想要的快照，你可以使用<command>svn copy</command>加参数 <option>-r 350</option>。</para>
<para>但是等一下：标签的产生过程与建立分支是一样的？是的，实际上在Subversion中标签与分支没有区别，都是普通的目录，通过copy命令得到，与分支一样，一个目录之所以是标签只是<emphasis>人们</emphasis>决定这样使用它，只要没有人提交这个目录，它永远是一个快照，但如果人们开始提交，它就变成了分支。</para>
- <para>如果你管理一个版本库，你有两种方式管理标签，第一种方法是禁止命令：作为项目的政策，我们要决定标签所在的位置，确定所有用户知道如何处理拷贝的目录（也就是确保他们不会提交他们），第二种方法看来很过分：使用访问控制脚本来阻止任何想对标签目录做的非拷贝的操作（见<xref linkend="svn-ch-6"/>）这种方法通常是不必要的，如果一个人不小心提交了到标签目录一个修改，你可以简单的取消，毕竟这是版本控制啊。</para>
+ <para>如果你管理一个版本库，你有两种方式管理标签，第一种方法是禁止命令：作为项目的政策，我们要决定标签所在的位置，确定所有用户知道如何处理拷贝的目录（也就是确保他们不会提交他们），第二种方法看来很过分：使用访问控制脚本来阻止任何想对标签目录做的非拷贝的操作（见<xref linkend="svn.serverconfig"/>）这种方法通常是不必要的，如果一个人不小心提交了到标签目录一个修改，你可以简单的取消，毕竟这是版本控制啊。</para>
</sect2>
- <sect2 id="svn-ch-4-sect-6.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.tags.mkcomplex">
<title>建立复杂的标签</title>
<para>有时候你希望你的<quote>快照</quote>能够很复杂，而不只是一个单独修订版本的一个单独目录。</para>
@@ -957,7 +974,7 @@
<para>现在在版本库有一个新的目录<filename>/calc/tags/mytag</filename>，这是你的本地拷贝的一个快照—混合了修订版本，URL等等。</para>
<para>一些人也发现这一特性一些有趣的使用方式，有些时候本地拷贝有一组本地修改，你希望你的协作者看到这些，不使用<command>svn
- diff</command>并发送一个不定文件（不会捕捉到目录修改），而是使用<command>svn copy</command>来<quote>上传</quote>你的工作拷贝到一个版本库的私有区域，你的协作者可以选择完整的取出你的工作拷贝，或使用<command>svn
+ diff</command>并发送一个补定文件（不会捕捉到目录、符号链和属性的修改），而是使用<command>svn copy</command>来<quote>上传</quote>你的工作拷贝到一个版本库的私有区域，你的协作者可以选择完整的取出你的工作拷贝，或使用<command>svn
merge</command>来接受你的精确修改。</para>
</sect2>
@@ -965,14 +982,15 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 7 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-4-sect-7">
+ <!-- ================================================================= -->
+ <sect1 id="svn.branchmerge.maint">
<title>分支维护</title>
<para>你一定注意到了Subversion极度的灵活性，因为它用相同的底层机制（目录拷贝）实现了分支和标签，因为分支和标签是作为普通的文件系统出现，会让人们感到害怕，因为它<emphasis>太</emphasis>灵活了，在这个小节里，我们会提供安排和管理数据的一些建议。</para>
- <sect2 id="svn-ch-4-sect-7.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.maint.layout">
<title>版本库布局</title>
<para>有一些标准的，推荐的组织版本库的方式，许多人创建一个<filename>trunk</filename>目录来保存开发的<quote>主线</quote>，一个<filename>branches</filename>目录存放分支拷贝，一个目录保存标签拷贝，如果一个版本库只是存放一个项目，人们会在顶级目录创建这些目录：</para>
@@ -984,7 +1002,7 @@
</screen>
<para>如果一个版本库保存了多个项目，管理员会通过项目来布局（见<xref
- linkend="svn-ch-5-sect-6.1"/>关于<quote>项目根目录</quote>）：</para>
+ linkend="svn.reposadmin.projects.chooselayout"/>关于<quote>项目根目录</quote>）：</para>
<screen>
/paint/trunk
@@ -1003,7 +1021,8 @@
</sect2>
- <sect2 id="svn-ch-4-sect-7.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.maint.lifetime">
<title>数据的生命周期</title>
<para>另一个Subversion模型的可爱特性是分支和标签可以有有限的生命周期，就像其它的版本化的项目，举个例子，假定你最终完成了<filename>calc</filename>项目你的个人分支上的所有工作，在合并了你的所有修改到<filename>/calc/trunk</filename>后，没有必要继续保留你的私有分支目录：</para>
@@ -1044,9 +1063,9 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 8 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-4-sect-8">
+ <!-- ================================================================= -->
+ <sect1 id="svn.branchmerge.summary">
<title>摘要</title>
<para>我们已经在本章覆盖了许多基础知识，我们讨论了标签和分支的概念，然后描述了Subversion怎样用<command>svn copy</command>命令拷贝目录实现了这些概念，我们也已经展示了怎样使用<command>svn merge</command>命令来在分支之间拷贝修改，或是撤销错误的修改。我们仔细研究了使用<command>svn switch</command>来创建混合位置的工作拷贝，然后我们也讨论了怎样管理和组织版本库中分支的生命周期。</para>
Modified: trunk/src/zh/book/ch05.xml
==============================================================================
--- trunk/src/zh/book/ch05.xml (original)
+++ trunk/src/zh/book/ch05.xml Wed Jan 25 01:01:34 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="svn-ch-5">
+<chapter id="svn.reposadmin">
<title>版本库管理</title>
<simplesect>
@@ -12,20 +12,16 @@
</footnote>您一定要关注一下本章的内容。</para>
</simplesect>
- <!-- ******************************************************************* -->
-
- <!-- *** 第一部分: 版本库基本知识 *** -->
-
- <!-- ******************************************************************* -->
-
- <sect1 id="svn-ch-5-sect-1">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.reposadmin.basics">
<title>版本库基本知识</title>
<para>在进入版本库管理这块宽广的主题之前，让我们进一步确定一下版本库的定义，它是怎样工作的？让人有什么感觉？它希望茶是热的还是冰的，加糖或柠檬吗？作为一名管理员，你应该既从逻辑视角－数据在版本库中如何展示，又能从物理具体细节的视角－版本库如何响应一个非Subversion的工具，来理解版本库的组成。下面的小节从一个比较高的层面覆盖了这些基本概念。</para>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-1.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.basics.txnsrevs">
<title>理解事务和修订版本</title>
<para>从概念上来说，Subversion的版本库就是一串目录树。每一个目录树，就是版本库的文件和目录在某一时刻的快照。这些快照是客户端使用者操作的结果，叫做修订版本。</para>
@@ -39,9 +35,8 @@
<para>理论上，有一天整个流程能够发展到对事务进行更加细密的流程控制。可以想象一个系统，在客户端完成操作，将要保存到版本库中时，每个加到它的事务都变成一个修订版本。这将会使每一个新的提交都可以被别人查看到，也许是主管，也许是质量保证小组，他们可以决定是要接收这个事务成为修订版本，还是放弃它。</para>
</sect2>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-1.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.basics.revprops">
<title>未受版本控制的属性</title>
<para>事务和修订版本在Subversion版本库中可以附加属性。这些属性就是普通的属性名和属性值的映射，被用来存储与对应目录树有关的信息。这些属性名和属性值跟你的其他数据一样，被存储在版本库文件系统中。</para>
@@ -51,18 +46,20 @@
<para>修订版本和事务的属性都是未受版本控制的－因为当它们被修改时，先前的值就被完全舍弃了。修订版本树自身是不能变更的，与之关联的属性可以修改。你可在日后添加、删除、修改修订版本的属性。如果你提交一个新的修订版本之后意识到遗漏了一些信息或在日志中的拼写错误，你可以直接以正确的信息覆盖<literal>svn:log</literal>它的值。</para>
</sect2>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-1.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.basics.backends">
<title>版本库数据存储</title>
- <para>在Subversion1.1中，版本库中存储数据有两种方式。一种是在Berkeley DB数据库中存储数据；另一种是使用普通的文件，使用自定义格式。因为Subversion的开发者称版本库为[版本化的]文件系统，他们接受了称后一种存储方式为FSFS的习惯，也就是说，使用本地操作系统文件系统来存储数据的版本化文件系统。</para>
+ <para>在Subversion1.1中，版本库中存储数据有两种方式。一种是在Berkeley DB数据库中存储数据；另一种是使用普通的文件，使用自定义格式。因为Subversion的开发者称版本库为（版本化的）文件系统，他们接受了称后一种存储方式为FSFS<footnote>
+ <para>读作<quote>fuzz-fuzz</quote>, 如果Jack
+ Repenning说起这个问题。</para>
+ </footnote>的习惯，也就是说，使用本地操作系统文件系统来存储数据的版本化文件的系统。</para>
<para>建立一个版本库时，管理员必须决定使用Berkeley DB还是FSFS。它们各有优缺点，我们将详细描述。这两个中并没有一个是更正式的，访问版本库的程序与采用哪一种实现方式无关。访问程序并不知道版本库如何存储数据，它们只是从版本库的API读取到修订版本和事务树。</para>
- <para>下面的表从总体上比较了Berkeley DB和FSFS版本库，下一部分将会详细讲述细节。</para>
+ <para><xref linkend="svn.reposadmin.basics.backends.tbl-1"/>从总体上比较了Berkeley DB和FSFS版本库，下一部分将会详细讲述细节。</para>
- <table id="svn-ch-5-table-1">
+ <table id="svn.reposadmin.basics.backends.tbl-1">
<title>版本库数据存储对照表</title>
<tgroup cols="3">
@@ -168,9 +165,7 @@
</tgroup>
</table>
- <!-- *****************************************************************-->
-
- <sect3 id="svn-ch-5-sect-1.3.1">
+ <sect3 id="svn.reposadmin.basics.backends.bdb">
<title>Berkeley DB</title>
<para>在Subversion的初始设计阶段，开发者因为多种原因而决定采用Berkeley
@@ -179,19 +174,17 @@
<para>Berkeley DB提供了真正的事务支持－这或许是它最强大的特性，访问你的Subversion版本库的多个进程不必担心偶尔会破坏其他进程的数据。事务系统提供的隔离对于任何给定的操作，Subversion版本库代码看到的只是数据库的静态视图－而不是一个在其他进程影响不断变化的数据库－并能够根据该视图作出决定。如果该决定正好同其他进程所做操作冲突，整个操作会回滚，就像什么都没有发生一样，并且Subversion会优雅的再次对更新的静态视图进行操作。</para>
<para>Berkeley DB另一个强大的特性是热备份－不必<quote>脱机</quote>就可以备份数据库环境的能力。我们将会在<xref
- linkend="svn-ch-5-sect-3.6" />讨论如何备份你的版本库，能够不停止系统对版本库做全面备份的好处是显而易见的。</para>
+ linkend="svn.reposadmin.maint.backup"/>讨论如何备份你的版本库，能够不停止系统对版本库做全面备份的好处是显而易见的。</para>
<para>Berkeley DB同时是一个可信赖的数据库系统。Subversion利用了Berkeley DB可以记日志的便利，这意味着数据库先在磁盘上写一个日志文件，描述它将要做的修改，然后再做这些修改。这是为了确保如果如果任何地方出了差错，数据库系统能恢复到先前的检查点—一个日志文件认为没有错误的位置，重新开始事务直到数据恢复为一个可用的状态。关于Berkeley DB日志文件的更多信息请查看<xref
- linkend="svn-ch-5-sect-3.3" />。</para>
+ linkend="svn.reposadmin.maint.diskspace"/>。</para>
<para>但是每朵玫瑰都有刺，我们也必须记录一些Berkeley DB已知的缺陷。首先，Berkeley DB环境不是跨平台的。你不能简单的拷贝一个在Unix上创建的Subversion版本库到一个Windows系统并期望它能够正常工作。尽管Berkeley DB数据库的大部分格式是不受架构约束的，但环境还是有一些方面没有独立出来。其次，使用Berkeley DB的Subversion不能在95/98系统上运行—如果你需要将版本库建在一个Windows机器上，请装到Windows2000或WindowsXP上。另外，Berkeley DB版本库不能放在网络共享文件夹中，尽管Berkeley DB承诺如果按照一套特定规范的话，可以在网络共享上正常运行，但实际上已知的共享类型几乎都不满足这套规范。</para>
- <para>最后，因为Berkeley DB的库直接链接到了Subversion中，它对于中断比典型的关系型数据库系统更为敏感。大多数SQL系统，举例来说，有一个主服务进程来协调对数据库表的访问。如果一个访问数据库的程序因为某种原因出现问题，数据库守护进程察觉到连接中断会做一些清理。因为数据库守护进程是唯一访问数据库表的进程，应用程序不需要担心访问许可的冲突。但是，这些情况与Berkeley DB不同。Subversion（和使用Subversion库的程序）直接访问数据库的表，这意味着如果有一个程序崩溃，就会使数据库处于一个暂时的不一致、不可访问的状态。当这种情况发生时，管理员需要让Berkeley DB恢复到一个检查点，这的确有点讨厌。除了崩溃的进程，还有一些情况能让版本库出现异常，比如程序在数据库文件的所有权或访问权限上发生冲突。因为Berkeley DB版本库非常快，并且可以扩展，非常适合使用一个单独的服务进程，通过一个用户来访问—比如Apache的<command>httpd</command>或<command>svnserve</command>（参见<xref linkend="svn-ch-6" />）—而不是多用户通过<literal>file:///</literal>或<literal>svn+ssh://</literal>URL的方式多用户访问。如果将Berkeley DB版本库直接用作多用户访问，请先阅读<xref linkend="svn-ch-6-sect-5" />。</para>
+ <para>最后，因为Berkeley DB的库直接链接到了Subversion中，它对于中断比典型的关系型数据库系统更为敏感。大多数SQL系统，举例来说，有一个主服务进程来协调对数据库表的访问。如果一个访问数据库的程序因为某种原因出现问题，数据库守护进程察觉到连接中断会做一些清理。因为数据库守护进程是唯一访问数据库表的进程，应用程序不需要担心访问许可的冲突。但是，这些情况与Berkeley DB不同。Subversion（和使用Subversion库的程序）直接访问数据库的表，这意味着如果有一个程序崩溃，就会使数据库处于一个暂时的不一致、不可访问的状态。当这种情况发生时，管理员需要让Berkeley DB恢复到一个检查点，这的确有点讨厌。除了崩溃的进程，还有一些情况能让版本库出现异常，比如程序在数据库文件的所有权或访问权限上发生冲突。因为Berkeley DB版本库非常快，并且可以扩展，非常适合使用一个单独的服务进程，通过一个用户来访问—比如Apache的<command>httpd</command>或<command>svnserve</command>（参见<xref linkend="svn.serverconfig"/>）—而不是多用户通过<literal>file:///</literal>或<literal>svn+ssh://</literal>URL的方式多用户访问。如果将Berkeley DB版本库直接用作多用户访问，请先阅读<xref linkend="svn.serverconfig.multimethod"/>。</para>
</sect3>
- <!-- ***************************************************************** -->
-
- <sect3 id="svn-ch-5-sect-1.3.2">
+ <sect3 id="svn.reposadmin.basics.backends.fsfs">
<title>FSFS</title>
<para>在2004年中期，另一种版本库存储系统慢慢形成了：一种不需要数据库的存储系统。FSFS版本库在单一文件中存储修订版本树，所以版本库中所有的修订版本都在一个子文件夹中有限的几个文件里。事务在单独的子目录中被创建，创建完成后，一个单独的事务文件被创建并移动到修订版本目录，这保证提交是原子性的。因为一个修订版本文件是持久不可改变的，版本库也可以做到热备份，就象Berkeley DB版本库一样。</para>
@@ -209,13 +202,11 @@
</sect2>
</sect1>
- <!-- ******************************************************************* -->
-
- <!-- *** 第二部分: 版本库创建和配置 *** -->
-
- <!-- ******************************************************************* -->
-
- <sect1 id="svn-ch-5-sect-2">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.reposadmin.create">
+
<title>版本库的创建和配置</title>
<para>创建一个 Subversion 版本库出乎寻常的简单。 Subversion
@@ -227,8 +218,8 @@
<para>这个命令在目录<filename>/path/to/repos</filename>创建了一个新的版本库。这个新的版本库会以修订版本版本0开始其生命周期，里面除了最上层的根目录(<filename>/</filename>)，什么都没有。刚开始，修订版本0有一个修订版本属性<literal>svn:date</literal>，设置为版本库创建的时间。</para>
- <para>在 Subversion 1.1中，版本库默认使用Berkeley
- DB后端存储方式来创建。在以后的发行版中这个行为会被改变。不管怎样，存储类型可以使用<option>--fs-type</option>参数明确说明。:</para>
+ <para>在 Subversion 1.2中，版本库默认使用FSFS后端存储方式来创建（见<xref
+ linkend="svn.reposadmin.basics.backends"/>）。不管怎样，存储类型可以使用<option>--fs-type</option>参数明确说明。:</para>
<screen>
$ svnadmin create --fs-type fsfs /path/to/repos
@@ -238,7 +229,7 @@
<warning>
<para>不要在网络共享上创建Berkeley DB版本库—它不能存在于诸如NFS， AFS或Windows SMB的远程文件系统中，Berkeley 数据要求底层文件系统实现严格的POSIX锁定语义，几乎没有任何网络文件系统提供这些特性，假如你在网络共享上使用Berkeley DB，结果是不可预知的——许多错误可能会立刻发现，也有可能在几个月之后才能发现</para>
- <para>假如你需要多台计算机来访问，你需要在网络共享上创建FSFS版本库，而不是Berkeley DB的版本库。或者更好的办法，你建立一个真正的服务进程（例如Apache或<command>svnserve），把版本库放在</command>服务器能访问到的本地文件系统中，以便能通过网络访问。详情请参看<xref linkend="svn-ch-6" /></para>
+ <para>假如你需要多台计算机来访问，你需要在网络共享上创建FSFS版本库，而不是Berkeley DB的版本库。或者更好的办法，你建立一个真正的服务进程（例如Apache或<command>svnserve），把版本库放在</command>服务器能访问到的本地文件系统中，以便能通过网络访问。详情请参看linkend="svn.serverconfig"/>。</para>
</warning>
<para>你可能已经注意到了，<command>svnadmin</command>命令的路径参数只是一个普通的文件系统路径，而不是一个<command>svn</command>客户端程序访问版本库时使用的URL。<command>svnadmin</command>和<command>svnlook</command>都被认为是服务器端工具—它们在版本库所在的机器上使用，用来检查或修改版本库，不能通过网络来执行任务。一个Subversion的新手通常会犯的错误，就是试图将URL（甚至<quote>本地</quote><literal>file:</literal>路径）传给这两个程序。</para>
@@ -312,9 +303,8 @@
<para>一般来说，你不需要手动干预版本库。<command>svnadmin</command>工具应该足以用来处理对版本库的任何修改，或者你也可以使用第三方工具（比如Berkeley DB的工具包）来调整部分版本库。不过还是会有些例外情况，我们会在这里提到。</para>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-2.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.create.hooks">
<title>钩子脚本</title>
<para>所谓<firstterm>钩子</firstterm>就是与一些版本库事件触发的程序，例如新修订版本的创建，或是未版本化属性的修改。每个钩子都会被告知足够多的信息，包括那是什么事件，所操作的对象，和触发事件的用户名。通过钩子的输出或返回状态，钩子程序能让工作继续、停止或是以某种方式挂起。</para>
@@ -325,9 +315,9 @@
<screen>
$ ls repos/hooks/
-post-commit.tmpl pre-revprop-change.tmpl
-post-revprop-change.tmpl start-commit.tmpl
-pre-commit.tmpl
+post-commit.tmpl post-unlock.tmpl pre-revprop-change.tmpl
+post-lock.tmpl pre-commit.tmpl pre-unlock.tmpl
+post-revprop-change.tmpl pre-lock.tmpl start-commit.tmpl
</screen>
<para>对每种Subversion版本库支持的钩子的都有一个模板，通过查看这些脚本的内容，你能看到是什么事件触发了脚本及如何给传脚本传递数据。同时，这些模版也是如何使用这些脚本，结合Subversion支持的工具来完成有用任务的例子。要实际安装一个可用的钩子，你需要在<filename>repos/hooks</filename>目录下安装一些与钩子同名（如 <command>start-commit</command>或者<command>post-commit</command>）的可执行程序或脚本。</para>
@@ -335,7 +325,7 @@
<tip> <para>由于安全原因，Subversion版本库在一个空环境中执行钩子脚本—就是没有任何环境变量，甚至没有<literal>$PATH</literal>或<literal>%PATH%</literal>。由于这个原因，许多管理员会感到很困惑，它们的钩子脚本手工运行时正常，可在Subversion中却不能运行。要注意，必须在你的钩子中设置好环境变量或为你的程序指定好绝对路径。</para>
</tip>
- <para>目前Subversion有已实现了五种钩子：</para>
+ <para>目前Subversion有已实现了九种钩子：</para>
<variablelist>
<varlistentry>
@@ -352,7 +342,7 @@
<para>Subversion的分发版本包括了一些访问控制脚本（在Subversion源文件目录树的<filename>tools/hook-scripts</filename>目录），可以用来被<command>pre-commit</command>调用来实现精密的写访问控制。另一个选择是使用Apache的httpd模块<command>mod_authz_svn</command>，可以对单个目录进行读写访问控制（见<xref
- linkend="svn-ch-6-sect-4.4.2"/>）。在未来的Subversion版本中,我们计划直接在文件系统中实现访问控制列表（ACLs）。</para>
+ linkend="svn.serverconfig.httpd.authz.perdir"/>）。在未来的Subversion版本中,我们计划直接在文件系统中实现访问控制列表（ACLs）。</para>
</listitem>
</varlistentry>
@@ -393,6 +383,71 @@
</para>
</listitem>
</varlistentry>
+
+
+ <varlistentry>
+ <term><filename>pre-lock</filename></term>
+ <listitem>
+ <para>This hook runs whenever someone attempts to lock a
+ file. It can be used to prevent locks altogether, or to
+ create a more complex policy specifying exactly which
+ users are allowed to lock particular paths. If the hook
+ notices a pre-existing lock, then it can also decide
+ whether a user is allowed to <quote>steal</quote> the
+ existing lock. The repository passes three arguments to
+ the hook: the path to the repository, the path being
+ locked, and the user attempting to perform the lock. If
+ the program returns a non-zero exit value, the lock
+ action is aborted and anything printed to stderr is
+ marshalled back to the client.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>post-lock</filename></term>
+ <listitem>
+ <para>This hook runs after a path is locked. The locked
+ path is passed to the hook's stdin, and the hook also
+ receives two arguments: the path to the repository, and
+ the user who performed the lock. The hook is then free
+ to send email notification or record the event in any
+ way it chooses. Because the lock already happened, the
+ output of the hook is ignored.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>pre-unlock</filename></term>
+ <listitem>
+ <para>This hook runs whenever someone attempts to remove a
+ lock on a file. It can be used to create policies that
+ specify which users are allowed to unlock particular
+ paths. It's particularly important for determining
+ policies about lock breakage. If user A locks a file,
+ is user B allowed to break the lock? What if the lock
+ is more than a week old? These sorts of things can be
+ decided and enforced by the hook. The repository passes
+ three arguments to the hook: the path to the repository,
+ the path being unlocked, and the user attempting to
+ remove the lock. If the program returns a non-zero exit
+ value, the unlock action is aborted and anything printed
+ to stderr is marshalled back to the client.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>post-unlock</filename></term>
+ <listitem>
+ <para>This hook runs after a path is unlocked. The
+ unlocked path is passed to the hook's stdin, and the
+ hook also receives two arguments: the path to the
+ repository, and the user who removed the lock. The hook
+ is then free to send email notification or record the
+ event in any way it chooses. Because the lock removal
+ already happened, the output of the hook is
+ ignored.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
<warning>
@@ -407,7 +462,8 @@
</sect2>
- <sect2 id="svn-ch-5-sect-2.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.create.bdb">
<title>Berkeley DB配置</title>
<para>Berkeley DB环境是对一个或多个数据库、日志文件、区域文件和配置文件的封装。Berkeley DB环境对许多参数有自己的缺省值，例如任何时间里可用的锁定数目、日志文件的最大值等。Subversion文件系统会使用Berkeley DB的默认值。 不过，有时候你的特定版本库与它独特的数据集合和访问类型，可能需要不同的配置选项。</para>
@@ -419,25 +475,21 @@
</sect2>
</sect1>
- <!-- ******************************************************************* -->
-
- <!-- *** SECTION 3: 版本库维护 *** -->
-
- <!-- ******************************************************************* -->
-
- <sect1 id="svn-ch-5-sect-3">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.reposadmin.maint">
<title>版本库维护</title>
<para>维护一个Subversion版本库是一项令人沮丧的工作，主要因为有数据库后端与生俱来的复杂性。做好这项工作需要知道一些工具——它们是什么，什么时候用以及如何使用。这一节将会向你介绍Subversion自带的版本库管理工具，以及如何使用它们来完成诸如版本库移植、升级、备份和整理之类的任务。</para>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-3.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.maint.tk">
<title>管理员的工具箱</title>
<para>Subversion提供了一些用来创建、查看、修改和修复版本库的工具。让我们首先详细了解一下每个工具，然后，我们再看一下仅在Berkeley DB后端分发版本中提供的版本数据库工具。</para>
- <sect3 id="svn-ch-5-sect-3.1.1">
+ <sect3 id="svn.reposadmin.maint.tk.svnlook">
<title>svnlook</title>
<para><command>svnlook</command>是Subversion提供的用来查看版本库中不同的修订版本和事务。这个程序不会修改版本库内容－这是个<quote>只读</quote>的工具。<command>svnlook</command>通常用在版本库钩子程序中，用来记录版本库即将提交（<command>用在pre-commit钩子时）</command>或者已经提交的（用在<command>post-commit</command>钩子时）修改。版本库管理员可以将这个工具用于诊断。</para>
@@ -616,6 +668,13 @@
</varlistentry>
<varlistentry>
+ <term><literal>lock</literal></term>
+ <listitem>
+ <para>If a path is locked, describe the lock attributes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>
<literal>log</literal>
</term>
@@ -677,7 +736,7 @@
</variablelist>
</sect3>
- <sect3 id="svn-ch-5-sect-3.1.2">
+ <sect3 id="svn.reposadmin.maint.tk.svnadmin">
<title>svnadmin</title>
<para><command>svnadmin</command>程序是版本库管理员最好的朋友。除了提供创建Subversion版本库的功能，这个程序使你可以维护这些版本库。<command>svnadmin</command>的语法跟 <command>svnlook</command>类似：</para>
@@ -695,7 +754,7 @@
…
</screen>
- <para>我们已经提过<command>svnadmin</command>的<literal>create</literal>子命令（参照<xref linkend="svn-ch-5-sect-2" />）。本章中我们会详细讲解大多数其他的命令。现在，我们来简单的看一下每个可用的子命令提供了什么功能。</para>
+ <para>我们已经提过<command>svnadmin</command>的<literal>create</literal>子命令（参照<xref linkend="svn.reposadmin.create"/>）。本章中我们会详细讲解大多数其他的命令。现在，我们来简单的看一下每个可用的子命令提供了什么功能。</para>
<variablelist>
<varlistentry>
@@ -765,7 +824,15 @@
<para>导入由<literal>dump</literal>子命令导出的可移植转储格式的一组修订版本。</para>
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term><literal>lslocks</literal></term>
+ <listitem>
+ <para>List and describe any locks that exist in the
+ repository.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>
<literal>lstxns</literal>
@@ -787,6 +854,14 @@
</varlistentry>
<varlistentry>
+ <term><literal>rmlocks</literal></term>
+ <listitem>
+ <para>Unconditionally remove locks from listed
+ paths.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>
<literal>rmtxns</literal>
</term>
@@ -818,7 +893,7 @@
</variablelist>
</sect3>
- <sect3 id="svn-ch-5-sect-3.1.3">
+ <sect3 id="svn.reposadmin.maint.tk.svndumpfilter">
<title>svndumpfilter</title>
<para>因为Subversion使用底层的数据库储存各类数据，手工调整是不明智的，即使这样做并不困难。何况，一旦你的数据存进了版本库，通常很难再将它们从版本库中删除。<footnote>
@@ -826,7 +901,7 @@
</footnote>但是不可避免的，总会有些时候你需要处理版本库的历史数据。你也许想把一个不应该出现的文件从版本库中彻底清除。或者，你曾经用一个版本库管理多个工程，现在又想把它们分开。要完成这样的工作，管理员们需要更易于管理和扩展的方法表示版本库中的数据，Subversion版本库转储文件格式就是一个很好的选择。</para>
<para>Subversion版本库转储文件记录了所有版本数据的变更信息，而且以易于阅读的格式保存。可以使用<command>svnadmin dump</command>命令生成转储文件，然后用<command>svnadmin load</command>命令生成一个新的版本库。（参见 <xref
- linkend="svn-ch-5-sect-3.5" />）。转储文件易于阅读意味着你可以小心翼翼的查看和修改它。当然，问题是如果你有一个运行了两年的版本库，那么生成的转储文件会很庞大，阅读和手工修改起来都会花费很多时间。</para>
+ linkend="svn.reposadmin.maint.migrate"/>）。转储文件易于阅读意味着你可以小心翼翼的查看和修改它。当然，问题是如果你有一个运行了两年的版本库，那么生成的转储文件会很庞大，阅读和手工修改起来都会花费很多时间。</para>
<para>虽然在管理员的日常工作中并不会经常使用，不过<command>svndumpfilter</command>可以对特定的路径进行过滤。这是一个独特而很有意义的用法，可以帮助你快速方便的修改转储的数据。使用时，只需提供一个你想要保留的（或者不想保留的）路径列表，然后把你的版本库转储文件送进这个过滤器。最后你就可以得到一个仅包含你想保留的路径的转储数据流。</para>
@@ -868,7 +943,7 @@
</variablelist>
<para>现在我来演示如何使用这个命令。我们会在其它章节（参见 <xref
- linkend="svn-ch-5-sect-6.1" />）讨论关于如何选择设定版本库布局的问题，比如应该使用一个版本库管理多个项目还是使用一个版本库管理一个项目，或者如何在版本库中安排数据等等。不过，有些时候，即使在项目已经展开以后，你还是希望对版本库的布局做一些调整。最常见的情况是，把原来存放在同一个版本库中的几个项目分开，各自成家。</para>
+ linkend="svn.reposadmin.projects.chooselayout"/>）讨论关于如何选择设定版本库布局的问题，比如应该使用一个版本库管理多个项目还是使用一个版本库管理一个项目，或者如何在版本库中安排数据等等。不过，有些时候，即使在项目已经展开以后，你还是希望对版本库的布局做一些调整。最常见的情况是，把原来存放在同一个版本库中的几个项目分开，各自成家。</para>
<para>假设有一个包含三个项目的版本库：
<literal>calc</literal>，<literal>calendar</literal>，和
@@ -999,78 +1074,11 @@
<para>此外，复制操作生成的路径也会带来麻烦。Subversion支持在版本库中进行复制操作，也就是复制一个存在的路径，生成一个新的路径。问题是，<command>svndumpfilter</command>保留的某个文件或目录可能是由某个<command>svndumpfilter</command>排除的文件或目录复制而来的。也就是说，为了确保转储数据的完整性，<command>svndumpfilter</command>需要切断这些复制自被排除路径的文件与源文件的关系，还要将这些文件的内容以新建的方式添加到转储数据中。但是由于Subversion版本库转储文件格式中仅包含了修订版本的更改信息，因此源文件的内容基本上无法获得。如果你不能确定版本库中是否存在类似的情况，最好重新考虑一下到底保留/排除哪些路径。</para>
</sect3>
- <sect3 id="svn-ch-5-sect-3.1.4">
- <title>svnshell.py</title>
-
- <para>Subversion源代码树中有一个类似于shell的版本库访问界面。Python脚本<command>svnshell.py</command>（位于源代码树的<filename>tools/examples/</filename>下）通过Subversion语言绑定接口（所以运行这个脚本须要正确的编译和安装这些程序包）连接到版本库和文件系统库。</para>
-
- <para>运行这个脚本，你可以浏览版本库中的目录，就像在shell下浏览文件系统一样。一开始，你<quote>位于</quote>修订版本<literal>HEAD</literal>的根目录中， 在命令提示符中可以看到相应的提示。 任何时候都可以使用<literal>help</literal>命令显示当前可用的命令帮助。</para>
-
- <screen>
-$ svnshell.py /path/to/repos
-<rev: 2 />$ help
-Available commands:
- cat FILE : dump the contents of FILE
- cd DIR : change the current working directory to DIR
- exit : exit the shell
- ls [PATH] : list the contents of the current directory
- lstxns : list the transactions available for browsing
- setrev REV : set the current revision to browse
- settxn TXN : set the current transaction to browse
- youngest : list the youngest browsable revision number
-<rev: 2 />$
-</screen>
-
- <para>浏览版本库的目录结构就像在Unix或Windows shell中一样——使用<literal>cd</literal>命令。任何时候，命令提示符中都会显示当前所在的修订版本（前缀为<literal>rev:</literal>）或事务（前缀为<literal>txn:</literal>，以及你所在的路径。你可以用<literal>setrev</literal>和<literal>settxn</literal>切换到其它修订版本或事务中去。你可以像在Unix shell中那样，使用<literal>ls</literal>命令列出目录的内容，使用<literal>cat</literal>命令列出文件的内容。</para>
-
- <example id="svn-ch-8-sect-3.1.3-ex-1">
- <title>使用svnshell浏览版本库</title>
-
- <screen>
-<rev: 2 />$ ls
- REV AUTHOR NODE-REV-ID SIZE DATE NAME
-----------------------------------------------------------------------------
- 1 sally < 2.0.1> Nov 15 11:50 A/
- 2 harry < 1.0.2> 56 Nov 19 08:19 iota
-<rev: 2 />$ cd A
-<rev: 2 /A>$ ls
- REV AUTHOR NODE-REV-ID SIZE DATE NAME
-----------------------------------------------------------------------------
- 1 sally < 4.0.1> Nov 15 11:50 B/
- 1 sally < a.0.1> Nov 15 11:50 C/
- 1 sally < b.0.1> Nov 15 11:50 D/
- 1 sally < 3.0.1> 23 Nov 15 11:50 mu
-<rev: 2 /A>$ cd D/G
-<rev: 2 /A/D/G>$ ls
- REV AUTHOR NODE-REV-ID SIZE DATE NAME
-----------------------------------------------------------------------------
- 1 sally < e.0.1> 23 Nov 15 11:50 pi
- 1 sally < f.0.1> 24 Nov 15 11:50 rho
- 1 sally < g.0.1> 24 Nov 15 11:50 tau
-<rev: 2 /A>$ cd ../..
-<rev: 2 />$ cat iota
-This is the file 'iota'.
-Added this text in revision 2.
-
-<rev: 2 />$ setrev 1; cat iota
-This is the file 'iota'.
-
-<rev: 1 />$ exit
-$
-</screen>
- </example>
-
- <para>在上例中可以看到，可以将几条命令现在同一行中，并以分号隔开。此外，这个shell也能正确处理相对路径和绝对路径，以及特殊的路径<literal>.</literal>和<literal>..</literal>。</para>
-
- <para><literal>youngest</literal>命令将列出最年轻的修订版本。这可以用来确定<literal>setrev</literal>命令参数的范围—你可以浏览所有0到最年轻修订版本中的任何一个（它们都以整数为标识）。确定可以浏览的事务就不这么简单了。你需要使用<command>lstxns</command>命令列出哪些事务可以浏览。<command>lstxns</command>命令的输出与<command>svnadmin lstxns</command>的输出相同，设置了<option>--transaction</option>选项的<command>svnlook</command>命令也可以得到相同的结果。</para>
-
- <para>使用<command>exit</command>命令可以退出这个shell。也可以使用文件结束符—Control-D（在某些Win32的Python版本中用Control-Z代替）。</para>
- </sect3>
-
- <sect3 id="svn-ch-5-sect-3.1.5">
+ <sect3 id="svn.reposadmin.maint.tk.bdbutil">
+
<title>Berkeley DB工具</title>
- <para>如果你使用Berkeley DB版本库，那么所有纳入版本控制的文件系统结构和数据都储存在一系列数据库的表中，而这个位于版本库的<filename>db</filename>子目录下。这个子目录是一个标准的Berkeley DB环境目录，可以应用任何Berkeley数据库工具进行操作（参考SleepyCat网站<systemitem class="url">http://www.sleepycat.com/</systemitem>上关于这些工具的介绍）。</para>
+ <para>如果你使用Berkeley DB版本库，那么所有纳入版本控制的文件系统结构和数据都储存在一系列数据库的表中，而这个位于版本库的<filename>db</filename>子目录下。这个子目录是一个标准的Berkeley DB环境目录，可以应用任何Berkeley数据库工具进行操作（参考SleepyCat网站<ulink url="http://www.sleepycat.com/"/>上关于这些工具的介绍）。</para>
<para>对于Subversion的日常使用来说，这些工具并没有什么用处。大多数Subversion版本库必须的数据库操作都集成到<command>svnadmin</command>工具中。比如，<command>svnadmin list-unused-dblogs</command>和<command>svnadmin list-dblogs</command>实现了Berkeley <command>db_archive</command>命令功能的一个子集，而<command>svnadmin recover</command>则起到了 <command>db_recover</command>工具的作用。</para>
@@ -1078,9 +1086,8 @@
</sect3>
</sect2>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-3.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.maint.cleanup">
<title>版本库清理</title>
<para>Subversion版本库一旦按照需要配置完成，一般情况下不需要特别的关照。不过有些时候还是需要管理员手工干预一下。<command>svnadmin</command>工具就能够帮你完成以下这类工作：</para>
@@ -1106,7 +1113,7 @@
<para><command>svnadmin</command>的子命令中最经常用到的恐怕就是<literal>setlog</literal>。用户在提交时输入的日志信息随着相关事务提交到版本库并升级成为修订版本后，便作为新修订版本的非版本化（即没有进行版本管理）属性保存下来。换句话说，版本库只记得最新的属性值，而忽略以前的。</para>
<para>有时用户输入的日志信息有错误（比如拼写错误或者内容错误）。如果配置版本库时设置了（使用<literal>pre-revprop-change</literal>和 <literal>post-revprop-change</literal>钩子；参见<xref
- linkend="svn-ch-5-sect-2.1" />）允许用户在提交后修改日志信息的选项，那么用户可以使用<command>svn</command>程序的<literal>propset</literal>命令（参见<xref linkend="svn-ch-9" />）<quote>修正</quote>日志信息中的错误。不过为了避免永远丢失信息，Subversion版本库通常设置为仅能由管理员修改非版本化属性（这也是默认的选项）。</para>
+ linkend="svn.reposadmin.create.hooks"/>）允许用户在提交后修改日志信息的选项，那么用户可以使用<command>svn</command>程序的<literal>propset</literal>命令（参见<xref linkend="svn.ref"/>）<quote>修正</quote>日志信息中的错误。不过为了避免永远丢失信息，Subversion版本库通常设置为仅能由管理员修改非版本化属性（这也是默认的选项）。</para>
<para>如果管理员想要修改日志信息，那么可以使用<command>svnadmin setlog</command>命令。这个命令从指定的文件中读取信息，取代版本库中某个修订版本的日志信息（<literal>svn:log</literal>属性）。</para>
@@ -1144,7 +1151,7 @@
<para>在按照上面例子中的方法清理版本库之前，你或许应该暂时关闭版本库和客户端的连接。这样在你开始清理之前，不会有正常的事务进入版本库。下面例子中的shell脚本可以用来迅速获得版本库中异常事务的信息：</para>
- <example id="svn-ch-5-sect-3.2-ex-1">
+ <example id="svn.reposadmin.maint.cleanup.ex-1">
<title>txn-info.sh（异常事务报告）</title>
<programlisting>
@@ -1167,7 +1174,7 @@
</example>
<para>可以用下面的命令使用上例中脚本：
- <command>/path/to/txn-info.sh /path/to/repos</command>。该命令的输出主要由多个<command>svnlook info</command>参见<xref linkend="svn-ch-5-sect-3.1.1" />）的输出组成，类似于下面的例子：</para>
+ <command>/path/to/txn-info.sh /path/to/repos</command>。该命令的输出主要由多个<command>svnlook info</command>参见<xref linkend="svn.reposadmin.maint.tk.svnlook"/>）的输出组成，类似于下面的例子：</para>
<screen>
$ txn-info.sh myrepos
@@ -1192,9 +1199,8 @@
<para>简言之，作出事务清理的决定前应该仔细考虑一下。许多信息源—比如Apache的错误和访问日志，已成功完成的Subversion提交日志等等—都可以作为决策的参考。管理员还可以直接和那些似乎已经死亡事务的提交者直接交流（比如通过邮件），来确认该事务确实已经死亡了。</para>
</sect2>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-3.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.maint.diskspace">
<title>管理磁盘空间</title>
<para>虽然存储器的价格在过去的几年里以让人难以致信的速度滑落，但是对于那些需要对大量数据进行版本管理的管理员们来说，磁盘空间的消耗依然是一个重要的因素。版本库每增加一个字节都意味着需要多一个字节的磁盘空间进行备份，对于多重备份来说，就需要消耗更多的磁盘空间。Berkeley DB版本库的主要存储机制是基于一个复杂的数据库系统建立的，因此了解一些数据性质是有意义的，比如哪些数据必须保留。哪些数据需要备份、哪些数据可以安全的删除等等。本节的内容专注于Berkeley DB类型的版本库。FSFS类型的版本库不需要进行数据清理和回收。</para>
@@ -1223,12 +1229,11 @@
</note>
</sect2>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-3.4">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.maint.recovery">
<title>版本库的恢复</title>
- <para><xref linkend="svn-ch-5-sect-1.3.1" />中曾提到，Berkeley DB版本库如果没有正常关闭可能会进入冻结状态。这时，就需要管理员将数据库恢复到正常状态。</para>
+ <para><xref linkend="svn.reposadmin.basics.backends.bdb"/>中曾提到，Berkeley DB版本库如果没有正常关闭可能会进入冻结状态。这时，就需要管理员将数据库恢复到正常状态。</para>
<para>Berkeley DB使用一种锁机制保护版本库中的数据。锁机制确保数据库不会同时被多个访问进程修改，也就保证了从数据库中读取到的数据始终是稳定而且正确的。当一个进程需要修改数据库中的数据时，首先必须检查目标数据是否已经上锁。如果目标数据没有上锁，进程就将它锁上，然后作出修改，最后再将锁解除。而其它进程则必须等待锁解除后才能继续访问数据库中的相关内容。</para>
@@ -1273,9 +1278,8 @@
<para>如果因为某些原因，上面的方法没能成功的恢复版本库，那么你可以做两件事。首先，将破损的版本库保存到其它地方，然后从最新的备份中恢复版本库。然后，发送一封邮件到Subversion用户列表（地址是：<email>users at subversion.tigris.org</email>），写清你所遇到的问题。对于Subversion的开发者来说，数据安全是最重要的问题。</para>
</sect2>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-3.5">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.maint.migrate">
<title>版本库的移植</title>
<para>Subversion文件系统将数据保存在许多数据库表中，而这些表的结构只有Subversion开发者们才了解（也只有他们才感兴趣）不过，有些时候我们会想到把所有的数据（或者一部分数据）保存在一个独立的、可移植的、普通格式的文件中。Subversion通过<command>svnadmin</command>的两个子命令<literal>dump</literal>和<literal>load</literal>提供了类似的功能。</para>
@@ -1305,7 +1309,7 @@
<listitem>
<para>如果移植的同时改变的版本库的访问地址（比如移植到另一台计算机或者改变了访问策略），那么可以通知用户运行<command>svn switch --relocate</command>来切换他们的工作副本。参见<xref
- linkend="svn-ch-9-sect-1.2-re-switch" />。</para>
+ linkend="svn.ref.svn.c.switch"/>。</para>
</listitem>
</orderedlist>
@@ -1356,6 +1360,25 @@
</screen>
+ <para>The result of a load is new revisions added to a
+ repository—the same thing you get by making commits
+ against that repository from a regular Subversion client. And
+ just as in a commit, you can use hook scripts to perform
+ actions before and after each of the commits made during a load
+ process. By passing the <option>--use-pre-commit-hook</option>
+ and <option>--use-post-commit-hook</option> options to
+ <command>svnadmin load</command>, you can instruct Subversion
+ to execute the pre-commit and post-commit hook scripts,
+ respectively, for each loaded revision. You might use these,
+ for example, to ensure that loaded revisions pass through the
+ same validation steps that regular commits pass through. Of
+ course, you should use these options with care—if your
+ post-commit hook sends emails to a mailing list for each new
+ commit, you might not want to spew hundreds or thousands of
+ commit emails in rapid succession at that list for each of the
+ loaded revisions! You can read more about the use of hook
+ scripts in <xref linkend="svn.reposadmin.create.hooks"/>.</para>
+
<para>既然<command>svnadmin</command>使用标准输入流和标准输出流作为转储和装载的输入和输出，那么更漂亮的用法是（管道两端可以是不同版本的<command>svnadmin</command>：</para>
<screen>
@@ -1426,20 +1449,19 @@
<para>我们再介绍一下Subversion版本库转储数据的最后一种用途——在不同的存储机制或版本控制系统之间转换。因为转储数据的格式的大部分是可以阅读的，<footnote>
<para>Subversion版本库的转储文件格式类似于RFC-822格式，后者广泛的应用于电子邮件系统中。</para>
- </footnote>所以使用这种格式描述变更集（每个变更集对应一个新的修订版本）会相对容易一些。事实上，<command>cvs2svn.py</command>工具（参见
- <xref linkend="svn-ap-a-sect-11" />）正是将CVS版本库的内容转换为转储数据格式，如此才能将CVS版本库的数据导入Subversion版本库之中。</para>
+ </footnote>所以使用这种格式描述变更集（每个变更集对应一个新的修订版本）会相对容易一些。事实上，<command>cvs2svn</command>工具（参见
+ <xref linkend="svn.forcvs.convert"/>）正是将CVS版本库的内容转换为转储数据格式，如此才能将CVS版本库的数据导入Subversion版本库之中。</para>
</sect2>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-3.6">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.maint.backup">
<title>版本库备份</title>
<para>尽管现代计算机的诞生带来了许多便利，但有一件事听起来是完全正确的—有时候，事情变的糟糕，很糟糕，动力损耗、网络中断、坏掉的内存和损坏的硬盘都是对魔鬼的一种体验，即使对于最尽职的管理员，命运也早已注定。所以我们来到了这个最重要的主题—怎样备份你的版本库数据。</para>
<para>Subversion版本库管理员通常有两种备份方式—增量的和完全的。我们在早先的章节曾经讨论过如何使用<command>svnadmin
dump --incremental</command>命令执行增量备份（见<xref
- linkend="svn-ch-5-sect-3.5" />），从本质上讲，这个方法只是备份了从你上次备份版本库到现在的变化。</para>
+ linkend="svn.reposadmin.maint.migrate"/>），从本质上讲，这个方法只是备份了从你上次备份版本库到现在的变化。</para>
<para>一个完全的版本库备份照字面上讲就是对整个版本库目录的复制（包括伯克利数据库或者文件FSFS环境），现在，除非你临时关闭了其他对版本库的访问，否则仅仅做一次迭代的拷贝会有产生错误备份的风险，因为有人可能会在并行的写数据库。</para>
@@ -1447,7 +1469,7 @@
<para>甚至当你用了一个增量备份时，你也会希望有计划的运行这个程序。举个例子，你考虑在你的调度程序（如Unix下的<command>cron</command>）里加入<command>hot-backup.py</command>，或者你喜欢更加细致的备份解决方案，你可以让你的post-commit的钩子脚本执行<command>hot-backup.py</command>（见see
<xref
- linkend="svn-ch-5-sect-2.1" />），这样会导致你的版本库的每次提交执行一次备份，只要在你的<filename>hooks/post-commit</filename>脚本里添加如下代码：</para>
+ linkend="svn.reposadmin.create.hooks" />），这样会导致你的版本库的每次提交执行一次备份，只要在你的<filename>hooks/post-commit</filename>脚本里添加如下代码：</para>
<programlisting>
(cd /path/to/hook/scripts; ./hot-backup.py ${REPOS} /path/to/backups &)
@@ -1473,20 +1495,16 @@
</sect2>
</sect1>
- <!-- ******************************************************************* -->
-
- <!-- *** SECTION 6: ADDING PROJECTS *** -->
-
- <!-- ******************************************************************* -->
-
- <sect1 id="svn-ch-5-sect-6">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.reposadmin.projects">
<title>添加项目</title>
<para>一旦你的版本库已经建立并且配置好了，剩下的就是使用了。如果你已经准备好了需要版本控制的数据，那么可以使用客户端软件<command>svn</command>的<literal>import</literal>子命令来实现你的期望。不过在这样做之前，你最好对版本库仔细的作一个长远的规划。本节，我们会给你一些好的建议，这些建议可以帮助你设计版本库的文件布局，以及如何在特定的布局中安排你的数据。</para>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-6.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.projects.chooselayout">
<title>选择一种版本库布局</title>
<para>在Subversion版本库中，移动版本化的文件和目录不会损失任何信息，但是这样一来那些经常访问版本库并且以为文件总是在同一个路径的用户可能会受到干扰。为将来着想，最好预先对你的版本库布局进行规划。以一种高效的<quote>布局</quote>开始项目，可以减少将来很多不必要的麻烦。</para>
@@ -1500,7 +1518,13 @@
<para>可以采用折中的办法。比如，可以把许多项目按照彼此之间的关联程度划分为几个组合，然后为每一个项目组合建立一个版本库。这样，在相关项目之间共享数据依旧很简单，而如果修订版本号有了变化，至少开发人员知道，改变的东西多少和他们有些关系。</para>
<para>在决定了如何用版本库组织项目以后，就该决定如何设置版本库的目录层次了。由于Subversion按普通的目录复制方式完成分支和标签操作（参见<xref
- linkend="svn-ch-4" />），Subversion社区建议为每一个项目建立一个<firstterm>项目根目录</firstterm>—项目的<quote>顶级</quote>目录—然后在根目录下建立三个子目录：<filename>trunk</filename>，保存项目的开发主线；<filename>branches</filename>，保存项目的各种开发分支；<filename>tags</filename>，保存项目的标签，也就是创建后永远不会修改的分支（可能会删除）。</para>
+ linkend="svn.branchmerge"/>），Subversion社区建议为每一个项目建立一个<firstterm>项目根目录</firstterm>—项目的<quote>顶级</quote>目录—然后在根目录下建立三个子目录：<filename>trunk</filename>，保存项目的开发主线；<filename>branches</filename>，保存项目的各种开发分支；<filename>tags</filename>，保存项目的标签，也就是创建后永远不会修改的分支（可能会删除）。
+ <footnote>
+ <para>The <filename>trunk</filename>, <filename>tags</filename>,
+ and <filename>branches</filename> trio are sometimes referred
+ to as <quote>the TTB directories</quote>.</para>
+ </footnote>
+ </para>
<para>举个例子，一个版本库可能会有如下的布局：</para>
@@ -1546,12 +1570,11 @@
<para>按照你因为合适方式安排版本库的布局。Subversion自身并不强制或者偏好某一种布局形式，对于Subversion来说，目录就是目录。最后，在设计版本库布局的时候，不要忘了考虑一下项目参与者们的意见。</para>
</sect2>
- <!-- ***************************************************************** -->
-
- <sect2 id="svn-ch-5-sect-6.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.reposadmin.projects.import">
<title>创建布局，导入初始数据</title>
- <para>设计好版本库的布局后，就该在版本库中实现布局和导入初始数据了。在Subversion中，有很多种方法完成这项工作。可以使用<command>svn mkdir</command>命令（参见<xref linkend="svn-ch-9" />）在版本库中逐个创建需要的目录。更快捷的方法是使用<command>svn import</command>命令（参见<xref linkend="svn-ch-3-sect-7.3" />）。首先，在硬盘上创建一个临时目录，并按照设计好的布局在其中创建子目录，然后通过导入命令一次性的提交整个布局到版本库中：</para>
+ <para>设计好版本库的布局后，就该在版本库中实现布局和导入初始数据了。在Subversion中，有很多种方法完成这项工作。可以使用<command>svn mkdir</command>命令（参见<xref linkend="svn.ref"/>）在版本库中逐个创建需要的目录。更快捷的方法是使用<command>svn import</command>命令（参见<xref linkend="svn.tour.other.import"/>）。首先，在硬盘上创建一个临时目录，并按照设计好的布局在其中创建子目录，然后通过导入命令一次性的提交整个布局到版本库中：</para>
<screen>
$ mkdir tmpdir
@@ -1591,17 +1614,15 @@
$
</screen>
- <para>创建了版本库布局以后，如果有项目的初始数据，那么可以将这些数据导入到版本库中。同样有很多种方法完成这项工作。首先，可以使用<command>svn import</command>命令。也可以先从版本库中取出工作副本，将已有的项目数据复制到工作副本中，再使用<command>svn add</command>和<command>svn commit</command>命令提交修改。不过这些工作就不属于版本库管理方面的内容了。如果对<command>svn</command> 客户端程序还不熟悉，请阅读<xref linkend="svn-ch-3" />。</para>
+ <para>创建了版本库布局以后，如果有项目的初始数据，那么可以将这些数据导入到版本库中。同样有很多种方法完成这项工作。首先，可以使用<command>svn import</command>命令。也可以先从版本库中取出工作副本，将已有的项目数据复制到工作副本中，再使用<command>svn add</command>和<command>svn commit</command>命令提交修改。不过这些工作就不属于版本库管理方面的内容了。如果对<command>svn</command> 客户端程序还不熟悉，请阅读<xref linkend="svn.tour"/>。</para>
</sect2>
</sect1>
- <!-- ******************************************************************* -->
-
- <!-- *** 第七部分: 总结 *** -->
-
- <!-- ******************************************************************* -->
-
- <sect1 id="svn-ch-5-sect-7">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.reposadmin.summary">
+
<title>摘要</title>
<para>现在，你应该已经对如何创建、配置以及维护Subversion版本库有了个基本的认识。我们向您介绍了几个可以帮助您工作的工具。通过这一章，我们说明了一些常见的管理误区，并提出了避免陷入误区的建议。</para>
Modified: trunk/src/zh/book/ch06.xml
==============================================================================
--- trunk/src/zh/book/ch06.xml (original)
+++ trunk/src/zh/book/ch06.xml Wed Jan 25 01:01:34 2006
@@ -1,4 +1,4 @@
-<chapter id="svn-ch-6">
+<chapter id="svn.serverconfig">
<title>配置服务器</title>
<simplesect>
@@ -11,9 +11,9 @@
</simplesect>
<!-- ================================================================= -->
- <!-- ======================== SECTION 1 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-6-sect-1">
+ <!-- ================================================================= -->
+ <sect1 id="svn.serverconfig.overview">
<title>概述</title>
@@ -22,10 +22,11 @@
<para>Apache是最流行的web服务器，通过使用<command>mod_dav_svn</command>模块，Apache可以访问版本库，并且可以使客户端使用HTTP的扩展协议WebDAV/DeltaV进行访问，另一个是<command>svnserve</command>：一个小的，独立服务器，使用自己定义的协议和客户端，表格6-1比较了这两种服务器。</para>
<para>需要注意到Subversion作为一个开源的项目，并没有官方的指定何种服务器是<quote>主要的</quote>或者是<quote>官方的</quote>，并没有那种网络实现被视作二等公民，每种服务器都有自己的优点和缺点，事实上，不同的服务器可以并行工作，分别通过自己的方式访问版本库，它们之间不会互相阻碍（见<xref
- linkend="svn-ch-6-sect-5"/>）。以下是对两种存在的Subversion服务器的比较—作为一个管理员，你更加胜任给你和你的用户挑选服务器的任务。</para>
+ linkend="svn.serverconfig.multimethod"/>）。<xref
+ linkend="svn.serverconfig.overview.tbl-1"/>是对两种存在的Subversion服务器的比较—作为一个管理员，你更加胜任给你和你的用户挑选服务器的任务。</para>
- <table id="svn-ch-6-table-1">
+ <table id="svn.serverconfig.overview.tbl-1">
<title>网络服务器比较</title>
<tgroup cols="3">
<thead>
@@ -108,40 +109,75 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 2 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-6-sect-2">
+ <!-- ================================================================= -->
+ <sect1 id="svn.serverconfig.netmodel">
<title>网络模型</title>
<para>这部分是讨论了Subversion客户端和服务器怎样互相交流，不考虑具体使用的网络实现，通过阅读，你会很好的理解服务器的行为方式和多种客户端与之响应的配置方式。</para>
- <sect2 id="svn-ch-6-sect-2.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.netmodel.reqresp">
<title>请求和响应</title>
<para>Subversion客户端花费大量的时间来管理工作拷贝，当它需要版本库信息，它会做一个网络请求，然后服务器给一个恰当的回答，具体的网络协议细节对用户不可见，客户端尝试去访问一个URL，根据URL模式的不同，会使用特定的协议与服务器联系（见<xref
- linkend="svn-ch-2-sidebar-1"/>），用户可以运行<command>svn
+ linkend="svn.basic.in-action.wc.sb-1"/>），用户可以运行<command>svn
--version</command>来查看客户端可以使用的URL模式和协议。</para>
<para>当服务器处理一个客户端请求，它通常会要求客户端确定它自己的身份，它会发出一个认证请求给客户端，而客户端通过提供<firstterm>凭证</firstterm>给服务器作为响应，一旦认证结束，服务器会响应客户端最初请求的信息。注意这个系统与CVS之类的系统不一样，它们会在请求之前，预先提供凭证（<quote>logs
in</quote>）给服务器，在Subversion里，服务器通过请求客户端适时地<quote>拖入</quote>凭证，而不是客户端<quote>推</quote>出。这使得这种操作更加的优雅，例如，如果一个服务器配置为世界上的任何人都可以读取版本库，在客户使用<command>svn
checkout</command>时，服务器永远不会发起一个认证请求。</para>
- <para>如果客户端请求往版本库写入新的数据（例如<command>svn commit</command>），这会建立新的修订版本树，如果客户端的请求是经过认证的，认证过的用户的用户名就会作为<literal>svn:author</literal>属性的值保存到新的修订本里（见<xref linkend="svn-ch-5-sect-1.2"/>）。如果客户端没有经过认证（换句话说，服务器没有发起过认证请求），这时修订本的<literal>svn:author</literal>的值是空的。<footnote><para>这个问题实际上是一个FAQ，源自错误的服务器配置。</para></footnote></para>
+ <para>如果客户端请求往版本库写入新的数据（例如<command>svn commit</command>），这会建立新的修订版本树，如果客户端的请求是经过认证的，认证过的用户的用户名就会作为<literal>svn:author</literal>属性的值保存到新的修订本里（见<xref linkend="svn.reposadmin.basics.revprops"/>）。如果客户端没有经过认证（换句话说，服务器没有发起过认证请求），这时修订本的<literal>svn:author</literal>的值是空的。<footnote><para>这个问题实际上是一个FAQ，源自错误的服务器配置。</para></footnote></para>
</sect2>
- <sect2 id="svn-ch-6-sect-2.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.netmodel.credcache">
<title>客户端凭证缓存</title>
<para>许多服务器配置为在每次请求时要求认证，这对一次次输入用户名和密码的用户来说是非常恼人的事情。</para>
<para>令人高兴的是，Subversion客户端对此有一个修补：存在一个在磁盘上保存认证凭证缓存的系统，缺省情况下，当一个命令行客户端成功的在服务器上得到认证，它会保存一个认证文件到用户的私有运行配置区—类Unix系统下会在<filename>~/.subversion/auth/</filename>，Windows下在<filename>%APPDATA%/Subversion/auth/</filename>（运行区在<xref
- linkend="svn-ch-7-sect-1"/>会有更多细节描述）。成功的凭证会缓存在磁盘，以主机名、端口和认证域的组合作为唯一性区别。</para>
+ linkend="svn.advanced.confarea"/>会有更多细节描述）。成功的凭证会缓存在磁盘，以主机名、端口和认证域的组合作为唯一性区别。</para>
<para>当客户端接收到一个认证请求，它会首先查找磁盘中的认证凭证缓存，如果没有发现，或者是缓存的凭证认证失败，客户端会提示用户需要这些信息。</para>
- <para>十分关心安全的人们一定会想<quote>把密码缓存在磁盘？太可怕了，永远不要这样做！</quote>但是请保持冷静，首先，<filename>auth/</filename>是访问保护的，只有用户（拥有者）可以读取这些数据，不是整个世界，如果这对你还不够安全，你可以关闭凭证缓存，只需要一个简单的命令，使用参数<option>--no-auth-cache</option>：</para>
+ <para>十分关心安全的人们一定会想<quote>把密码缓存在磁盘？太可怕了，永远不要这样做！</quote>但是请保持冷静，并没有你想象得那么可怕。</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>The <filename>auth/</filename> caching area is
+ permission-protected so that only the user (owner) can
+ read data from it, not the world at large. The operating
+ system's own file permissions are protecting the
+ password.</para>
+ </listitem>
+
+ <listitem>
+ <para>On Windows 2000 and later, the Subversion client uses
+ standard Windows cryptography services to encrypt the
+ password on disk. Because the encryption key is managed
+ by Windows and is tied to the user's own login
+ credentials, only the user can decrypt the cached
+ password. (Note: if the user's Windows account
+ password is changed, all of the cached passwords become
+ undecipherable. The Subversion client will behave as if
+ they don't exist, prompting for passwords when
+ required.)</para>
+ </listitem>
+
+ <listitem>
+ <para>For the truly paranoid willing to sacrifice all
+ convenience, it's possible to disable credential caching
+ altogether.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>你可以关闭凭证缓存，只需要一个简单的命令，使用参数<option>--no-auth-cache</option>：</para>
<screen>
$ svn commit -F log_msg.txt --no-auth-cache
@@ -159,19 +195,19 @@
$ svn commit -F new_msg.txt
Authentication realm: <svn://host.example.com:3690> example realm
Username: joe
-[...]
+…
</screen>
<para>或许，你希望永远关闭凭证缓存，你可以编辑你的运行<filename>配置</filename>文件（坐落在<filename>auth/</filename>目录），只需要把<literal>store-auth-creds</literal>设置为<literal>no</literal>，这样就不会有凭证缓存在磁盘。</para>
-<screen>
+ <screen>
[auth]
store-auth-creds = no
</screen>
<para>有时候，用户希望从磁盘缓存删除特定的凭证，为此你可以浏览到<filename>auth/</filename>区域，删除特定的缓存文件，凭证都是作为一个单独的文件缓存，如果你打开每一个文件，你会看到键和值，<literal>svn:realmstring</literal>描述了这个文件关联的特定服务器的域：</para>
-<screen>
+ <screen>
$ ls ~/.subversion/auth/svn.simple/
5671adf2865e267db74f09ba6f872c28
3893ed123b39500bca8a0b382839198e
@@ -232,34 +268,35 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 3 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-6-sect-3">
+ <!-- ================================================================= -->
+ <sect1 id="svn.serverconfig.svnserve">
<title>svnserve，一个自定义的服务器</title>
<para><command>svnserve</command>是一个轻型的服务器，可以同客户端通过在TCP/IP基础上的自定义有状态协议通讯，客户端通过使用开头为<literal>svn://</literal>或者<literal>svn+ssh://</literal><command>svnserve</command>的URL来访问一个<command>svnserve</command>服务器。这一小节将会解释运行<command>svnserve</command>的不同方式，客户端怎样实现服务器的认证，怎样配置版本库恰当的访问控制。</para>
- <sect2 id="svn-ch-6-sect-3.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.svnserve.invoking">
<title>调用服务器</title>
<para>有许多调用<command>svnserve</command>的方式，如果调用时没有参数，你只会看到一些帮助信息，然而，如果你计划使用<command>inetd</command>启动进程，你可以传递<option>-i</option>（<option>--inetd</option>）选项：</para>
-<screen>
+ <screen>
$ svnserve -i
( success ( 1 2 ( ANONYMOUS ) ( edit-pipeline ) ) )
</screen>
<para>当用参数<option>--inetd</option>调用时，<command>svnserve</command>会尝试使用自定义协议通过<emphasis>stdin</emphasis>和<emphasis>stdout</emphasis>来与Subversion客户端通话，这是使用<command>inetd</command>工作的标准方式，IANA为Subversion协议保留3690端口，所以在类Unix系统你可以在<filename>/etc/services</filename>添加如下的几行（如果他们还不存在）：</para>
-<screen>
+ <screen>
svn 3690/tcp # Subversion
svn 3690/udp # Subversion
</screen>
<para>如果系统是使用经典的类Unix的<command>inetd</command>守护进程，你可以在<filename>/etc/inetd.conf</filename>添加这几行：</para>
-<screen>
+ <screen>
svn stream tcp nowait svnowner /usr/bin/svnserve svnserve -i
</screen>
@@ -277,12 +314,12 @@
<para>当以守护模式运行<command>svnserve</command>时，你可以使用<option>--listen-port=</option>和<option>--listen-host=</option>选项来自定义<quote>绑定</quote>的端口和主机名。</para>
<para>也一直有第三种方式，使用<option>-t</option>选项的<quote>管道模式</quote>，这个模式假定一个分布式服务程序如<command>RSH</command>或<command>SSH</command>已经验证了一个用户，并且<emphasis>以这个用户</emphasis>调用了一个私有<command>svnserve</command>进程，<command>svnserve</command>运作如常（通过<emphasis>stdin</emphasis>和<emphasis>stdout</emphasis>通讯），并且可以设想通讯是自动转向到一种通道传递回客户端，当<command>svnserve</command>被这样的通道代理调用，确定认证用户对版本数据库有完全的读写权限，（见<xref
- linkend="svn-ch-6-sidebar-1"/>。）这与本地用户通过<literal>file:///</literal>URl访问版本库同样重要。</para>
+ linkend="svn.serverconfig.svnserve.invoking.sb-1"/>。）这与本地用户通过<literal>file:///</literal>URl访问版本库同样重要。</para>
- <sidebar id="svn-ch-6-sidebar-1">
+ <sidebar id="svn.serverconfig.svnserve.invoking.sb-1">
<title>服务器和访问许可：一个警告</title>
- <para>首先需要记住，一个Subversion版本库是一组数据库文件，任何进程直接访问版本库需要对整个版本库有正确的读写许可，如果你不仔细处理，这会变得很头痛，特别是当你使用Berkeley DB数据库而不是FSFS时，详细信息可以阅读<xref linkend="svn-ch-6-sect-5"/>。</para>
+ <para>首先需要记住，一个Subversion版本库是一组数据库文件，任何进程直接访问版本库需要对整个版本库有正确的读写许可，如果你不仔细处理，这会变得很头痛，特别是当你使用Berkeley DB数据库而不是FSFS时，详细信息可以阅读<xref linkend="svn.serverconfig.multimethod"/>。</para>
<para>第二点，当配置<command>svnserve</command>、Apache <command>httpd</command>或者其它任何服务器时，不要使用<literal>root</literal>用户（或者其它具备无限制权限的用户）启动服务器进程，根据所有权和版本库允许的权限，通常应该创建一个新的自定义用户，例如很多管理员会创建一个叫做<literal>svn</literal>的用户，赋予这个用户排他的拥有权和对Subversion版本库的导出权利，只让服务器以这个用户运行。</para>
</sidebar>
@@ -292,21 +329,22 @@
class="url">svn://host.example.com/usr/local/repositories/project1
</systemitem>来进行访问，为了提高安全性，你可以使用<command>svnserve</command>的<option>-r</option>选项，这样会限制只输出指定路径下的版本库：</para>
-<screen>
+ <screen>
$ svnserve -d -r /usr/local/repositories
…
</screen>
<para>使用<option>-r</option>可以有效地改变文件系统的根位置，客户端可以使用去掉前半部分的路径，留下的要短一些的（更加有提示性）URL：</para>
-<screen>
+ <screen>
$ svn checkout svn://host.example.com/project1
…
</screen>
</sect2>
- <sect2 id="svn-ch-6-sect-3.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.svnserve.auth">
<title>内置的认证和授权</title>
<para>如果一个客户端连接到<command>svnserve</command>进程，如下事情会发生：</para>
@@ -332,26 +370,26 @@
<para>在撰写本文时，服务器还只知道怎样发送CRAM-MD5<footnote><para>见RFC 2195。</para></footnote>认证请求，本质上讲，就是服务器发送一些数据到客户端，客户端使用MD5哈希算法创建这些数据组合密码的指纹，然后返回指纹，服务器执行同样的计算并且来计算结果的一致性，<emphasis>真正的密码并没有在互联网上传递。</emphasis></para>
<para>当然也有可能，如果客户端在外部通过通道代理认证，如<command>SSH</command>，在那种情况下，服务器简单的检验作为那个用户的运行，然后使用它作为认证用户名，更多信息请看<xref
- linkend="svn-ch-6-sect-3.4"/>。</para>
+ linkend="svn.serverconfig.svnserve.sshauth"/>。</para>
- <para>像你已经猜测到的，版本库的<filename>svnserve.conf</filename>文件是控制认证和授权政策的中央机构，这文件与其它配置文件格式相同（见<xref linkend="svn-ch-7-sect-1"/>）：小节名称使用方括号标记（<literal>[</literal>和<literal>]</literal>），注释以井号（<literal>#</literal>）开始，每一小节都有一些参数可以设置（<literal>variable =
+ <para>像你已经猜测到的，版本库的<filename>svnserve.conf</filename>文件是控制认证和授权政策的中央机构，这文件与其它配置文件格式相同（见<xref linkend="svn.advanced.confarea"/>）：小节名称使用方括号标记（<literal>[</literal>和<literal>]</literal>），注释以井号（<literal>#</literal>）开始，每一小节都有一些参数可以设置（<literal>variable =
value</literal>），让我们浏览这个文件并且学习怎样使用它们。</para>
- <sect3 id="svn-ch-6-sect-3.2.1">
+ <sect3 id="svn.serverconfig.svnserve.auth.users">
<title>创建一个用户文件和域</title>
<para>此时，<filename>svnserve.conf</filename>文件的<literal>[general]</literal>部分包括所有你需要的变量，开始先定义一个保存用户名和密码的文件和一个认证域：</para>
-<screen>
+ <screen>
[general]
password-db = userfile
realm = example realm
</screen>
<para><literal>realm</literal>是你定义的名称，这告诉客户端连接的<quote>认证命名空间</quote>，Subversion会在认证提示里显示，并且作为凭证缓存（见<xref
- linkend="svn-ch-6-sect-2.2"/>。）的关键字（还有服务器的主机名和端口），<literal>password-db</literal>参数指出了保存用户和密码列表文件，这个文件使用同样熟悉的格式，举个例子：</para>
+ linkend="svn.serverconfig.netmodel.credcache"/>。）的关键字（还有服务器的主机名和端口），<literal>password-db</literal>参数指出了保存用户和密码列表文件，这个文件使用同样熟悉的格式，举个例子：</para>
-<screen>
+ <screen>
[users]
harry = foopassword
sally = barpassword
@@ -361,12 +399,12 @@
</sect3>
- <sect3 id="svn-ch-6-sect-3.2.2">
+ <sect3 id="svn.serverconfig.svnserve.auth.general">
<title>设置访问控制</title>
<para><filename>svnserve.conf</filename>有两个或多个参数需要设置：它们确定未认证（匿名）和认证用户可以做的事情，参数<literal>anon-access</literal>和<literal>auth-access</literal>可以设置为<literal>none</literal>、<literal>read</literal>或者<literal>write</literal>，设置为<literal>none</literal>会限制所有方式的访问，<literal>read</literal>允许只读访问，而<literal>write</literal>允许对版本库完全的读/写权限：</para>
-<screen>
+ <screen>
[general]
password-db = userfile
realm = example realm
@@ -380,7 +418,7 @@
<para>实例中的设置实际上是参数的缺省值，你一定不要忘了设置它们，如果你希望更保守一点，你可以完全封锁匿名访问：</para>
-<screen>
+ <screen>
[general]
password-db = userfile
realm = example realm
@@ -392,19 +430,20 @@
auth-access = write
</screen>
- <para>注意<command>svnserve</command>只能识别<quote>整体</quote>的访问控制，一个用户可以有全体的读/写权限，或者只读权限，或没有访问权限，没有对版本库具体路径访问的细节控制，很多项目和站点，这种 访问控制已经完全足够了，然而，如果你希望单个目录访问控制，你会需要使用包括<command>mod_authz_svn</command>（见<xref linkend="svn-ch-5-sect-2.1"/>）的Apache，或者是使用<command>pre-commit</command>钩子脚本来控制写访问（见<xref linkend="svn-ch-5-sect-2.1"/>），Subversion的分发版本包含一个<command>commit-access-control.pl</command>和一个更加复杂的<command>svnperms.py</command>脚本可以作为pre-commit脚本使用。</para>
+ <para>注意<command>svnserve</command>只能识别<quote>整体</quote>的访问控制，一个用户可以有全体的读/写权限，或者只读权限，或没有访问权限，没有对版本库具体路径访问的细节控制，很多项目和站点，这种 访问控制已经完全足够了，然而，如果你希望单个目录访问控制，你会需要使用包括<command>mod_authz_svn</command>（见<xref linkend="svn.serverconfig.httpd.authz.perdir"/>）的Apache，或者是使用<command>pre-commit</command>钩子脚本来控制写访问（见<xref linkend="svn.reposadmin.create.hooks"/>），Subversion的分发版本包含一个<command>commit-access-control.pl</command>和一个更加复杂的<command>svnperms.py</command>脚本可以作为pre-commit脚本使用。</para>
</sect3>
</sect2>
- <sect2 id="svn-ch-6-sect-3.4">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.svnserve.sshauth">
<title>SSH认证和授权</title>
<para><command>svnserve</command>的内置认证会非常容易得到，因为它避免了创建真实的系统帐号，另一方面，一些管理员已经创建好了SSH认证框架，在这种情况下，所有的项目用户已经拥有了系统帐号和有能力<quote>SSH到</quote>服务器。</para>
<para>SSH与<command>svnserve</command>结合很简单，客户端只需要使用<literal>svn+ssh://</literal>的URL模式来连接：</para>
-<screen>
+ <screen>
$ whoami
harry
@@ -421,15 +460,15 @@
<para>这里要理解的最重要的事情是Subversion客户端<emphasis>不</emphasis>是连接到运行中的<command>svnserve</command>守护进程，这种访问方法不需要一个运行的守护进程，也不需要在必要时唤醒一个，它依赖于<command>ssh</command>来发起一个<command>svnserve</command>进程，然后网络断开后终止进程。</para>
- <para>当使用<literal>svn+ssh://</literal>的URL访问版本库时，记住是<command>ssh</command>提示请求认证，而<emphasis>不</emphasis>是<command>svn</command>客户端程序。这意味着密码不会有自动缓存（见<xref linkend="svn-ch-6-sect-2.2"/>），Subversion客户端通常会建立多个版本库的连接，但用户通常会因为密码缓存特性而没有注意到这一点，当使用<literal>svn+ssh://</literal>的URL时，用户会为<command>ssh</command>在每次建立连接时重复的询问密码感到讨厌，解决方案是用一个独立的SSH密码缓存工具，像类Unix系统的<command>ssh-agent</command>或者是Windows下的<command>pageant</command>。</para>
+ <para>当使用<literal>svn+ssh://</literal>的URL访问版本库时，记住是<command>ssh</command>提示请求认证，而<emphasis>不</emphasis>是<command>svn</command>客户端程序。这意味着密码不会有自动缓存（见<xref linkend="svn.serverconfig.netmodel.credcache"/>），Subversion客户端通常会建立多个版本库的连接，但用户通常会因为密码缓存特性而没有注意到这一点，当使用<literal>svn+ssh://</literal>的URL时，用户会为<command>ssh</command>在每次建立连接时重复的询问密码感到讨厌，解决方案是用一个独立的SSH密码缓存工具，像类Unix系统的<command>ssh-agent</command>或者是Windows下的<command>pageant</command>。</para>
<para>当在一个管道上运行时，认证通常是基于操作系统对版本库数据库文件的访问控制，这同Harry直接通过<literal>file:///</literal>的URL直接访问版本库非常类似，如果有多个系统用户要直接访问版本库，你会希望将他们放到一个常见的组里，你应该小心的使用umasks。（确定要阅读<xref
- linkend="svn-ch-6-sect-5"/>）但是即使是在管道模式时，文件<filename>svnserve.conf</filename>还是可以阻止用户访问，如<literal>auth-access = read</literal>或者<literal>auth-access
+ linkend="svn.serverconfig.multimethod"/>）但是即使是在管道模式时，文件<filename>svnserve.conf</filename>还是可以阻止用户访问，如<literal>auth-access = read</literal>或者<literal>auth-access
= none</literal>。</para>
- <para>你会认为SSH管道的故事该结束了，但还不是，Subversion允许你在运行配置文件<filename>config</filename>（见<xref linkend="svn-ch-7-sect-1"/>）创建一个自定义的管道行为方式，举个例子，假定你希望使用RSH而不是SSH，在<filename>config</filename>文件的<literal>[tunnels]</literal>部分作如下定义：</para>
+ <para>你会认为SSH管道的故事该结束了，但还不是，Subversion允许你在运行配置文件<filename>config</filename>（见<xref linkend="svn.advanced.confarea"/>）创建一个自定义的管道行为方式，举个例子，假定你希望使用RSH而不是SSH，在<filename>config</filename>文件的<literal>[tunnels]</literal>部分作如下定义：</para>
-<screen>
+ <screen>
[tunnels]
rsh = rsh
</screen>
@@ -437,7 +476,7 @@
<para>现在你可以通过指定与定义匹配的URL模式来使用新的管道定义：<literal>svn+rsh://host/path</literal>。当使用新的URL模式时，Subversion客户端实际上会在后台运行<command>rsh host svnserve -t</command>这个命令，如果你在URL中包括一个用户名（例如，<literal>svn+rsh://username@host/path</literal>），客户端也会在自己的命令中包含这部分（<command>rsh
username at host svnserve -t</command>），但是你可以定义比这个更加智能的新的管道模式：</para>
-<screen>
+ <screen>
[tunnels]
joessh = $JOESSH /opt/alternate/ssh -p 29934
</screen>
@@ -449,12 +488,13 @@
</sect2>
- <sect2 id="svn-ch-6-sect-3.5">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.svnserve.sshtricks">
<title>SSH配置技巧</title>
<para>不仅仅是可以控制客户端调用<command>ssh</command>方式，也可以控制服务器中的<command>sshd</command>的行为方式，在本小节，我们会展示怎样控制<command>sshd</command>执行<command>svnserve</command>，包括如何让多个用户分享同一个系统帐户。</para>
- <sect3 id="svn-ch-6-sect-3.5.1">
+ <sect3 id="svn.serverconfig.svnserve.sshtricks.setup">
<title>初始设置</title>
<para>作为开始，定位到你启动<command>svnserve</command>的帐号的主目录，确定这个账户已经安装了一套SSH公开/私有密钥对，用户可以通过公开密钥认证，因为所有如下的技巧围绕着使用SSH<filename>authorized_keys</filename>文件，密码认证在这里不会工作。</para>
@@ -462,38 +502,38 @@
<para>如果这个文件还不存在，创建一个<filename>authorized_keys</filename>文件（在UNIX下通常是<filename>~/.ssh/authorized_keys</filename>），这个文件的每一行描述了一个允许连接的公钥，这些行通常是下面的形式：
</para>
-<screen>
+ <screen>
ssh-dsa AAAABtce9euch.... user at example.com
</screen>
<para>第一个字段描述了密钥的类型，第二个字段是未加密的密钥本身，第三个字段是注释。然而，这是一个很少人知道的事实，可以使用一个<literal>command</literal>来处理整行：</para>
-<screen>
+ <screen>
command="program" ssh-dsa AAAABtce9euch.... user at example.com
</screen>
<para>当<literal>command</literal>字段设置后，SSH守护进程运行命名的程序而不是通常Subversion客户端询问的<command>svnserve -t</command>。这为实施许多服务器端技巧开启了大门，在下面的例子里，我们简写了文件的这些行：</para>
-<screen>
+ <screen>
command="program" TYPE KEY COMMENT
</screen>
</sect3>
- <sect3 id="svn-ch-6-sect-3.5.2">
+ <sect3 id="svn.serverconfig.svnserve.sshtricks.fixedcmd">
<title>控制调用的命令</title>
<para>因为我们可以指定服务器端执行的命令，我们很容易来选择运行一个特定的<command>svnserve</command>程序来并且传递给它额外的参数：</para>
-<screen>
+ <screen>
command="/path/to/svnserve -t -r /virtual/root" TYPE KEY COMMENT
</screen>
- <para>在这个例子里，<filename>/path/to/svnserve</filename>也许会是一个<command>svnserve</command>程序的包裹脚本，会来设置umask（见<xref linkend="svn-ch-6-sect-5"/>）。它也展示了怎样在虚拟根目录定位一个<command>svnserve</command>，就像我们经常在使用守护进程模式下运行<command>svnserve</command>一样。这样做不仅可以把访问限制在系统的一部分，也可以使用户不需要在<literal>svn+ssh://</literal>URL里输入绝对路径。</para>
+ <para>在这个例子里，<filename>/path/to/svnserve</filename>也许会是一个<command>svnserve</command>程序的包裹脚本，会来设置umask（见<xref linkend="svn.serverconfig.multimethod"/>）。它也展示了怎样在虚拟根目录定位一个<command>svnserve</command>，就像我们经常在使用守护进程模式下运行<command>svnserve</command>一样。这样做不仅可以把访问限制在系统的一部分，也可以使用户不需要在<literal>svn+ssh://</literal>URL里输入绝对路径。</para>
<para>多个用户也可以共享同一个帐号，作为为每个用户创建系统帐户的替代，我们创建一个公开/私有密钥对，然后在<filename>authorized_users</filename>文件里放置各自的公钥，一个用户一行，使用<option>--tunnel-user</option>选项：</para>
-<screen>
+ <screen>
command="svnserve -t --tunnel-user=harry" TYPE1 KEY1 harry at example.com
command="svnserve -t --tunnel-user=sally" TYPE2 KEY2 sally at example.com
</screen>
@@ -502,7 +542,7 @@
<para>最后要小心：设定通过公钥共享账户进行用户访问时还会允许其它形式的SSH访问，即使你设置了<filename>authorized_keys</filename>的<literal>command</literal>值，举个例子，用户仍然可以通过SSH得到shell访问，或者是通过服务器执行X11或者是端口转发。为了给用户尽可能少的访问权限，你或许希望在<literal>command</literal>命令之后指定一些限制选项：</para>
-<screen>
+ <screen>
command="svnserve -t --tunnel-user=harry",no-port-forwarding,\
no-agent-forwarding,no-X11-forwarding,no-pty \
TYPE1 KEY1 harry at example.com
@@ -516,17 +556,18 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 4 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-6-sect-4">
+ <!-- ================================================================= -->
+ <sect1 id="svn.serverconfig.httpd">
<title>httpd，Apache的HTTP服务器</title>
- <para>Apache的HTTP服务器是一个Subversion可以利用的<quote>重型</quote>网络服务器，通过一个自定义模块，<command>httpd</command>可以让Subversion版本库通过WebDAV/DeltaV协议在客户端前可见，WebDAV/DeltaV协议是HTTP 1.1的扩展（见<systemitem class="url">http://www.webdav.org/</systemitem>来查看详细信息）。这个协议利用了无处不在的HTTP协议是广域网的核心这一点，添加了写能力—更明确一点，版本化的写—能力。结果就是这样一个标准化的健壮的系统，作为Apache 2.0软件的一部分打包，被许多操作系统和第三方产品支持，网络管理员也不需要打开另一个自定义端口。 <footnote>
+ <para>Apache的HTTP服务器是一个Subversion可以利用的<quote>重型</quote>网络服务器，通过一个自定义模块，<command>httpd</command>可以让Subversion版本库通过WebDAV/DeltaV协议在客户端前可见，WebDAV/DeltaV协议是HTTP 1.1的扩展（见<ulink url="http://www.webdav.org/"/>来查看详细信息）。这个协议利用了无处不在的HTTP协议是广域网的核心这一点，添加了写能力—更明确一点，版本化的写—能力。结果就是这样一个标准化的健壮的系统，作为Apache 2.0软件的一部分打包，被许多操作系统和第三方产品支持，网络管理员也不需要打开另一个自定义端口。 <footnote>
<para>他们讨厌这样做。</para>
</footnote>这样一个Apache-Subversion服务器具备了许多<command>svnserve</command>没有的特性，但是也有一点难于配置，灵活通常会带来复杂性。</para>
- <para>下面的讨论包括了对Apache配置指示的引用，给了一些使用这些指示的例子，详细地描述不在本章的范围之内，Apache小组维护了完美的文档，公开存放在他们的站点<systemitem class="url">http://httpd.apache.org</systemitem>。例如，一个一般的配置参考位于<systemitem class="url">http://httpd.apache.org/docs-2.0/mod/directives.html</systemitem>。</para>
+ <para>下面的讨论包括了对Apache配置指示的引用，给了一些使用这些指示的例子，详细地描述不在本章的范围之内，Apache小组维护了完美的文档，公开存放在他们的站点<ulink url="http://httpd.apache.org"/>。例如，一个一般的配置参考位于<ulink url="
+ http://httpd.apache.org/docs-2.0/mod/directives.html"/>。</para>
<para>同样，当你修改你的Apache设置，很有可能会出现一些错误，如果你还不熟悉Apache的日志子系统，你一定需要认识到这一点。在你的文件<filename>httpd.conf</filename>里会指定Apache生成的访问和错误日志（<literal>CustomLog</literal>和<literal>ErrorLog</literal>指示）的磁盘位置。Subversion的mod_dav_svn使用Apache的错误日志接口，你可以浏览这个文件的内容查看信息来查找难于发现的问题根源。</para>
@@ -543,8 +584,8 @@
</screen>
</sidebar>
-
- <sect2 id="svn-ch-6-sect-4.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.httpd.prereqs">
<title>必备条件</title>
<para>为了让你的版本库使用HTTP网络，你基本上需要两个包里的四个部分。你需要Apache <command>httpd</command> 2.0和包括的<command>mod_dav</command> DAV模块，Subversion和与之一同分发的<command>mod_dav_svn</command>文件系统提供者模块，如果你有了这些组件，网络化你的版本库将非常简单，如：</para>
@@ -565,7 +606,8 @@
</sect2>
- <sect2 id="svn-ch-6-sect-4.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.httpd.basic">
<title>基本的Apache配置</title>
<para>一旦你安装了必须的组件，剩下的工作就是在<filename>httpd.conf</filename>里配置Apache，使用<literal>LoadModule</literal>来加载mod_dav_svn模块，这个指示必须先与其它Subversion相关的其它配置出现，如果你的Apache使用缺省布局安装，你的<command>mod_dav_svn</command>模块一定在Apache安装目录（通常是在<filename>/usr/local/apache2</filename>）的<filename>modules</filename>子目录，<literal>LoadModule</literal>指示的语法很简单，影射一个名字到它的共享库的物理位置：</para>
@@ -621,13 +663,14 @@
<para>如果你通过<literal>NameVirtualHost</literal>指示使用Apache的虚拟主机，你或许需要<literal>ServerAlias</literal>指示来指定额外的名称，再说一次，可以查看Apache文档的来得到更多细节。</para>
</sidebar>
- <para>在本阶段，你一定要考虑访问权限问题，如果你已经作为普通的web服务器运行过Apache，你一定有了一些内容—网页、脚本和其他。这些项目已经配置了许多在Apache下可以工作的访问许可，或者更准确一点，允许Apache与这些文件一起工作。Apache当作为Subversion服务器运行时，同样需要正确的访问许可来读写你的Subversion版本库。（见<xref linkend="svn-ch-6-sidebar-1"/>。）</para>
+ <para>在本阶段，你一定要考虑访问权限问题，如果你已经作为普通的web服务器运行过Apache，你一定有了一些内容—网页、脚本和其他。这些项目已经配置了许多在Apache下可以工作的访问许可，或者更准确一点，允许Apache与这些文件一起工作。Apache当作为Subversion服务器运行时，同样需要正确的访问许可来读写你的Subversion版本库。（见<xref linkend="svn.serverconfig.svnserve.invoking.sb-1"/>。）</para>
<para>你会需要检验权限系统的设置满足Subversion的需求，同时不会把以前的页面和脚本搞乱。这或许意味着修改Subversion的访问许可来配合Apache服务器已经使用的工具，或者可能意味着需要使用<filename>httpd.conf</filename>的<literal>User</literal>和<literal>Group</literal>指示来指定Apache作为运行的用户和Subversion版本库的组。并不是只有一条正确的方式来设置许可，每个管理员都有不同的原因来以特定的方式操作，只需要意识到许可关联的问题经常在为Apache配置Subversion版本库的过程中被疏忽。</para>
</sect2>
- <sect2 id="svn-ch-6-sect-4.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.httpd.authn">
<title>认证选项</title>
<para>此时，如果你配置的<filename>httpd.conf</filename>保存如下的内容</para>
@@ -653,7 +696,7 @@
</listitem>
</itemizedlist>
- <sect3 id="svn-ch-6-sect-4.3.1">
+ <sect3 id="svn.serverconfig.httpd.authn.basic">
<title>基本HTTP认证</title>
<para>最简单的客户端认证方式是通过HTTP基本认证机制，简单的使用用户名和密码来验证一个用户所自称的身份，Apache提供了一个<command>htpasswd</command>工具来管理可接受的用户名和密码，这些就是你希望赋予Subversion特别权限的用户，让我们给Sally和Harry赋予提交权限，首先，我们需要添加他们到密码文件。</para>
@@ -700,7 +743,7 @@
</screen>
<para>一定要阅读后面的部分（<xref
- linkend="svn-ch-6-sect-4.4"/>）来得到<literal>Require</literal>的细节，和授权政策的其他设置方法。</para>
+ linkend="svn.serverconfig.httpd.authz"/>）来得到<literal>Require</literal>的细节，和授权政策的其他设置方法。</para>
<para>需要警惕：HTTP基本认证的密码是用明文传输，因此非常不可靠的，如果你担心密码偷窥，最好是使用某种SSL加密，所以客户端认证使用<literal>https://</literal>而不是<literal>http://</literal>，为了方便，你可以配置Apache为自签名认证。
<footnote>
@@ -711,7 +754,7 @@
</sect3>
- <sect3 id="svn-ch-6-sect-4.3.2">
+ <sect3 id="svn.serverconfig.httpd.authn.sslcerts">
<title>SSL证书管理</title>
<para>商业应用需要越过公司防火墙的版本库访问，防火墙需要小心的考虑非认证用户<quote>吸取</quote>他们的网络流量的情况，SSL让那种形式的关注更不容易导致敏感数据泄露。</para>
@@ -745,7 +788,7 @@
</screen>
<para>这个对话看起来很熟悉，这是你会在web浏览器（另一种HTTP客户端，就像Subversion）经常看到的问题，如果你选择(p)ermanent选项，服务器证书会存放在你存放那个用户名和密码缓存（见<xref
- linkend="svn-ch-6-sect-2.2"/>。）的私有运行区<filename>auth/</filename>中，缓存后，Subversion会自动记住在以后的交流中信任这个证书。</para>
+ linkend="svn.serverconfig.netmodel.credcache"/>。）的私有运行区<filename>auth/</filename>中，缓存后，Subversion会自动记住在以后的交流中信任这个证书。</para>
<para>你的运行中<filename>servers</filename>文件也会给你能力可以让Subversion客户端自动信任特定的CA，包括全局的或是每主机为基础的，只需要设置<literal>ssl-authority-files</literal>为一组逗号隔开的PEM加密的CA证书列表：</para>
@@ -791,12 +834,13 @@
</sect2>
- <sect2 id="svn-ch-6-sect-4.4">
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.httpd.authz">
<title>授权选项</title>
<para>此刻，你已经配置了认证，但是没有配置授权，Apache可以要求用户认证并且确定身份，但是并没有说明这个身份的怎样允许和限制，这个部分描述了两种控制访问版本库的策略。</para>
- <sect3 id="svn-ch-6-sect-4.4.1">
+ <sect3 id="svn.serverconfig.httpd.authz.blanket">
<title>整体访问控制</title>
<para>最简单的访问控制形式是授权特定用户为只读版本库访问或者是读/写访问版本库。</para>
@@ -818,8 +862,7 @@
</Location>
</screen>
- <para>有时候，你不需要这样严密，举个例子，Subversion自己在<systemitem
- class="url">http://svn.collab.net/repos/svn</systemitem>的源代码允许全世界的人执行版本库的只读操作（例如检出我们的工作拷贝和使用浏览器浏览版本库），但是限定只有认证用户可以执行写操作。为了执行特定的限制，你可以使用<literal>Limit</literal>和<literal>LimitExcept</literal>配置指示，就像<literal>Location</literal>指示，这个区块有开始和结束标签，你需要在<literal><Location></literal>中添加这个指示。</para>
+ <para>有时候，你不需要这样严密，举个例子，Subversion自己在<ulink url="http://svn.collab.net/repos/svn"/>的源代码允许全世界的人执行版本库的只读操作（例如检出我们的工作拷贝和使用浏览器浏览版本库），但是限定只有认证用户可以执行写操作。为了执行特定的限制，你可以使用<literal>Limit</literal>和<literal>LimitExcept</literal>配置指示，就像<literal>Location</literal>指示，这个区块有开始和结束标签，你需要在<literal><Location></literal>中添加这个指示。</para>
<para>在<literal>Limit</literal>和<literal>LimitExcept</literal>中使用的参数是可以被这个区块影响的HTTP请求类型，举个例子，如果你希望禁止所有的版本库访问，只是保留当前支持的只读操作，你可以使用<literal>LimitExcept</literal>指示，并且使用<literal>GET</literal>，<literal>PROPFIND</literal>，<literal>OPTIONS</literal>和<literal>REPORT</literal>请求类型参数，然后前面提到过的<literal>Require valid-user</literal>指示将会在<literal><LimitExcept></literal>区块中而不是在<literal><Location></literal>区块。</para>
@@ -840,13 +883,13 @@
</Location>
</screen>
- <para>这里只是一些简单的例子，想看关于Apache访问控制<literal>Require</literal>指示的更深入信息，可以查看Apache文档中的教程集<systemitem
- class="url">http://httpd.apache.org/docs-2.0/misc/tutorials.html</systemitem>中的<literal>Security</literal>部分。</para>
+ <para>这里只是一些简单的例子，想看关于Apache访问控制<literal>Require</literal>指示的更深入信息，可以查看Apache文档中的教程集<ulink
+ url="http://httpd.apache.org/docs-2.0/misc/tutorials.html"/>中的<literal>Security</literal>部分。</para>
</sect3>
- <sect3 id="svn-ch-6-sect-4.4.2">
+ <sect3 id="svn.serverconfig.httpd.authz.perdir">
<title>每目录访问控制</title>
<para>也可以使用Apache的httpd模块<command>mod_authz_svn</command>更加细致的设置访问权限，这个模块收集客户端传递过来的不同的晦涩的URL信息，询问<command>mod_dav_svn</command>来解码，然后根据在配置文件定义的访问政策来裁决请求。</para>
@@ -865,7 +908,7 @@
<para>最简单的区块是允许任何人可以访问，在这个场景里，Apache决不会发送认证请求，所有的用户作为<quote>匿名</quote>对待。</para>
- <example id="svn-ch-6-sect-4.4.2-ex-1">
+ <example id="svn.serverconfig.httpd.authz.perdir.ex-1">
<title>匿名访问的配置实例。</title>
<programlisting>
<Location /repos>
@@ -880,7 +923,7 @@
<para>在另一个极端，你可以配置为拒绝所有人的认证，所有客户端必须提供证明自己身份的证书，你通过<literal>Require valid-user</literal>指示来阻止无条件的认证，并且定义一种认证的手段。</para>
- <example id="svn-ch-6-sect-4.4.2-ex-2">
+ <example id="svn.serverconfig.httpd.authz.perdir.ex-2">
<title>一个认证访问的配置实例。</title>
<programlisting>
<Location /repos>
@@ -903,7 +946,7 @@
<para>第三种流行的模式是允许认证和匿名用户的组合，举个例子，许多管理员希望允许匿名用户读取特定的版本库路径，但希望只有认证用户可以读（或者写）更多敏感的区域，在这个设置里，所有的用户开始时用匿名用户访问版本库，如果你的访问控制策略在任何时候要求一个真实的用户名，Apache将会要求认证客户端，为此，你可以同时使用<literal>Satisfy Any</literal>和<literal>Require valid-user</literal>指示。</para>
- <example id="svn-ch-6-sect-4.4.2-ex-3">
+ <example id="svn.serverconfig.httpd.authz.perdir.ex-3">
<title>一个混合认证/匿名访问的配置实例。</title>
<programlisting>
<Location /repos>
@@ -1000,14 +1043,24 @@
jane = r
</screen>
+ <para>Groups can also be defined to contain other
+ groups:</para>
+
+ <screen>
+[groups]
+calc-developers = harry, sally, joe
+paint-developers = frank, sally, jane
+everyone = @calc-developers, @paint-developers
+</screen>
+
<para>...并且非常接近。</para>
</sect3>
- <sect3 id="svn-ch-6-sect-4.4.3">
+ <sect3 id="svn.serverconfig.httpd.authz.pathauthzoff">
<title>关闭路径为基础的检查</title>
- <para><command>mod_dav_svn</command>模块做了许多工作来确定你标记为“不可读”的数据不会因意外而泄露，这意味着需要紧密监控通过<command>svn
+ <para><command>mod_dav_svn</command>模块做了许多工作来确定你标记为<quote>不可读</quote>的数据不会因意外而泄露，这意味着需要紧密监控通过<command>svn
checkout</command>或是<command>svn update</command>返回的路径和文件内容，如果这些命令遇到一些根据认证策略不是可读的路径，这个路径通常会被一起忽略，在历史或者重命名操作时—例如运行一个类似<command>svn cat -r OLD foo.c</command>的命令来操作一个很久以前改过名字的文件 — 如果一个对象的以前的名字检测到是只读的，重命令追踪就会终止。</para>
<para>所有的路径检查在有时会非常昂贵，特别是<command>svn
@@ -1015,7 +1068,7 @@
<para>在另一方面，也有一个安全舱门允许你用安全特性来交换速度，如果你不是坚持要求有每目录授权（如不使用 <command>mod_authz_svn</command>和类似的模块），你就可以关闭所有的路径检查，在你的<filename>httpd.conf</filename>文件，使用<literal>SVNPathAuthz</literal>指示：</para>
- <example id="svn-ch-6-sect-4.4.3-ex-1">
+ <example id="svn.serverconfig.httpd.authz.pathauthzoff.ex-1">
<title>关闭所有的路经检查</title>
<programlisting>
<Location /repos>
@@ -1027,18 +1080,19 @@
</programlisting>
</example>
- <para><literal>SVNPathAuthz</literal>指示缺省是打开的，当设置为“off”时，所有的路径为基础的授权都会关闭；<command>mod_dav_svn</command>停止对每个目录调用授权检查。</para>
+ <para><literal>SVNPathAuthz</literal>指示缺省是<quote>on</quote>，当设置为<quote>off</quote>时，所有的路径为基础的授权都会关闭；<command>mod_dav_svn</command>停止对每个目录调用授权检查。</para>
</sect3>
</sect2>
-
- <sect2 id="svn-ch-6-sect-4.5">
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.serverconfig.httpd.extra">
<title>额外的糖果</title>
<para>我们已经覆盖了关于认证和授权的Apache和mod_dav_svn的大多数选项，但是Apache还提供了许多很好的特性。</para>
- <sect3 id="svn-ch-6-sect-4.5.1">
+ <sect3 id="svn.serverconfig.httpd.extra.browsing">
<title>版本库浏览</title>
<para>一个非常有用的好处是使用Apache/WebDAV配置Subversion版本库时可以用普通的浏览器察看最新的版本库文件，因为Subversion使用URL来鉴别版本库版本化的资源，版本库使用的HTTP为基础的URL也可以直接输入到Web浏览器中，你的浏览器会发送一个<literal>GET</literal>请求到URL，根据访问的URL是指向一个版本化的目录还是文件，mod_dav_svn会负责列出目录列表或者是文件内容。</para>
@@ -1066,13 +1120,12 @@
<para>你的Web浏览器只会说普通的HTTP，也就是说它只会GET公共的URL，这个URL代表了最新版本的文件和目录，根据WebDAV/DeltaV规范，每种服务器定义了一种私有的URL语法来代表老的资源的版本，这个语法对客户端是不透明的，为了得到老的版本，一个客户端必须通过一种规范过程来<quote>发现</quote>正确的URL；这个过程包括执行一系列WebDAV PROPFIND请求和理解DeltaV概念，这些事情一般是你的web浏览器做不了的。</para>
<para>为了回答这些问题，一个明显的看老版本文件和目录的方式是带<option>--revision</option>参数的<command>svn
- list</command>和<command>svn cat</command>命令，为了在浏览器里察看老版本，你可以使用第三方的软件，一个好的例子是ViewCVS（<systemitem
- class="url">http://viewcvs.sourceforge.net/</systemitem>），ViewCVS最初写出来是为了在web显示CVS版本库，最新的带血的（此时正在编写）版本也已经可以理解Subversion版本库了。</para>
+ list</command>和<command>svn cat</command>命令，为了在浏览器里察看老版本，你可以使用第三方的软件，一个好的例子是ViewCVS（<ulink url="http://viewvc.tigris.org/"/>），ViewCVS最初写出来是为了在web显示CVS版本库，最新的带血的（此时正在编写）版本也已经可以理解Subversion版本库了。</para>
</sidebar>
</sect3>
- <sect3 id="svn-ch-6-sect-4.5.2">
+ <sect3 id="svn.serverconfig.httpd.extra.other">
<title>其它特性</title>
<para>Apache作为一个健壮的Web服务器的许多特性也可以用来增加Subversion的功能性和安全性，Subversion使用Neon与Apache通讯，这是一种一般的HTTP/WebDAV库，可以支持SSL和Deflate压缩（是<command>gzip</command>和<command>PKZIP</command>程序用来<quote>压缩</quote>文件为数据块的一样的算法）之类的机制。你只需要编译你希望Subversion和Apache需要的特性，并且正确的配置程序来使用这些特性。</para>
@@ -1082,7 +1135,7 @@
<para>不怎么有趣，但同样重要，是Apache和Subversion关系的一些特性，像可以指定自定义的端口（而不是缺省的HTTP的80）或者是一个Subversion可以被访问的虚拟主机名，或者是通过代理服务器访问的能力，这些特性都是Neon所支持的，所以Subversion轻易得到这些支持。</para>
<para>最后，因为<command>mod_dav_svn</command>是使用一个半完成的WebDAV/DeltaV方言，所以通过第三方的DAV客户端访问也是可能的，几乎所有的现代操作系统（Win32、OS X和Linux）都有把DAV服务器影射为普通的网络<quote>共享</quote>的内置能力，这是一个复杂的主题；察看<xref
- linkend="svn-ap-c"/>来得到更多细节。</para>
+ linkend="svn.webdav"/>来得到更多细节。</para>
</sect3>
@@ -1093,9 +1146,9 @@
<!-- ================================================================= -->
- <!-- ======================== SECTION 5 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-6-sect-5">
+ <!-- ================================================================= -->
+ <sect1 id="svn.serverconfig.multimethod">
<title>支持多种版本库访问方法</title>
Modified: trunk/src/zh/book/ch07.xml
==============================================================================
--- trunk/src/zh/book/ch07.xml (original)
+++ trunk/src/zh/book/ch07.xml Wed Jan 25 01:01:34 2006
@@ -1,4 +1,4 @@
-<chapter id="svn-ch-7">
+<chapter id="svn.advanced">
<title>高级主题</title>
<simplesect>
@@ -9,24 +9,20 @@
<para>本章重点介绍一些Subversion不常用的特性，在这里，我们会讨论Subversion的属性（或者说<quote>元数据</quote>）支持，和如何通过更改运行配置区来改变Subversion的缺省行为方式，我们会描述怎样使用外部定义来指导Subversion从多个版本库得到数据，我们会覆盖一些Subversion分发版本附加的客户端和服务器端的工具的细节。</para>
- <para>在阅读本章之前，你一定要熟悉Subversion对文件和目录的基本版本操作能力，如果你还没有阅读这些内容，或者是需要一个复习，我们建议你重读<xref
- linkend="svn-ch-2" />和<xref linkend="svn-ch-3" />，一旦你已经掌握了基础知识和本章的内容，你会变成Subversion的超级用户！
+ <para>在阅读本章之前，你一定要熟悉Subversion对文件和目录的基本版本操作能力，如果你还没有阅读这些内容，或者是需要一个复习，我们建议你重读linkend="svn.basic" />和<xref linkend="svn.tour" />，一旦你已经掌握了基础知识和本章的内容，你会变成Subversion的超级用户！
</para>
</simplesect>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 1: RUNTIME CONFIGURATION AREA *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-7-sect-1">
+ <sect1 id="svn.advanced.confarea">
<title>运行配置区</title>
<para>Subversion提供了许多用户可以控制的可选行为方式，许多是用户希望添加到所有的Subversion操作中的选项，为了避免强制用户记住命令行参数并且在每个命令中使用，Subversion使用配置文件，并且将配置文件保存在独立的Subversion配置区。</para>
<para>Subversion<firstterm>配置区</firstterm>是一个双层结构，保存了可选项的名称和值。通常，Subversion配置区是一个保存<firstterm>配置文件</firstterm>的特殊目录（第一层结构），目录中保存了一些标准INI格式的文本文件（文件中的<quote>section</quote>形成第二层结构）。这些文件可以简单用你喜欢的文本编辑器编辑（如Emacs或vi），而且保存了客户端可以读取的指示，用来指导用户的一些行为选项。</para>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-1.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.confarea.layout">
<title>配置区布局</title>
<para><command>svn</command>命令行客户端第一次执行时，会创建一个用户配置区，在类Unix系统中，配置区位于用户主目录中，名为<filename>.subversion</filename>。在Win32系统，Subversion创建一个名为<filename>Subversion</filename>的目录，这个目录通常位于用户配置目录（顺便说一句，通常是一个隐藏目录）的<filename>Application Data</filename>子目录下。然而，在Win32平台上，此目录的具体位置在不同的系统上是不一样的，由Windows注册表决定。
@@ -45,8 +41,8 @@
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-1.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.confarea.windows-registry">
<title>配置和Windows注册表</title>
<para>除了基于INI文件的配置区，运行在Windows平台的Subversion客户端也可以使用Windows注册表来保存配置数据。注册表中保存的选项名称和值的含义与INI文件中相同，<quote>file/section</quote>在注册表中表现为注册表键树的层级，使得双层结构得以保留下来。</para>
@@ -77,7 +73,7 @@
<para><command>svn</command>命令行客户端不会尝试写Windows注册表，也不会在注册表中创建默认配置区。不过可以使用<command>REGEDIT</command>创建所需的键。此外，还可以创建一个<filename>.reg</filename>文件，并在文件浏览器中双击这个文件，文件中的数据就会合并到注册表中。</para>
- <example id="svn-ch-7-sect-1.2-ex-1">
+ <example id="svn.advanced.confarea.windows-registry.ex-1">
<title>注册表条目（.reg）样本文件。</title>
<programlisting>
@@ -125,13 +121,13 @@
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-1.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.confarea.opts">
<title>配置选项</title>
<para>本节我们会详细讨论Subversion目前支持的运行配置选项。</para>
- <sect3 id="svn-ch-7-sect-1.3.1">
+ <sect3 id="svn.advanced.confarea.opts.servers">
<title>服务器</title>
<para><filename>servers</filename>文件保存了Subversion关于网络层的配置选项，这个文件有两个特别的小节：<literal>groups</literal> 和<literal>global</literal>。<literal>groups</literal>小节是一个交叉引用表，其中的关键字是<filename>servers</filename>文件中其它小节的名字，值则是一个可以包含通配符的字符序列，对应于接收Subversion请求的主机名，称为glob。</para>
@@ -192,7 +188,7 @@
<varlistentry>
<term><literal>neon-debug-mask</literal></term>
<listitem>
- <para>只是一个整形的掩码，底层的HTTP库Neon用来选择产生调试的输出，缺省值是<literal>0</literal>，意思是关闭所有的调试输出，关于Subversion使用Neon的详细信息，见<xref linkend="svn-ch-8" />。</para>
+ <para>只是一个整形的掩码，底层的HTTP库Neon用来选择产生调试的输出，缺省值是<literal>0</literal>，意思是关闭所有的调试输出，关于Subversion使用Neon的详细信息，见<xref linkend="svn.developer" />。</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -222,7 +218,7 @@
</variablelist>
</sect3>
- <sect3 id="svn-ch-7-sect-1.3.2">
+ <sect3 id="svn.advanced.confarea.opts.config">
<title>config</title>
<para>其它的Subversion运行选项保存在<filename>config</filename>文件中，这些运行选项与网络连接无关，只是一些正在使用的选项，但是为了应对未来的扩展，也按小节划分成组。</para>
@@ -234,7 +230,7 @@
<term><literal>store-passwords</literal></term>
<listitem>
<para>这告诉Subversion是否缓存服务器认证要求时用户提供的密码，缺省值是<literal>yes</literal>。设置为<literal>no</literal>可以关闭在存盘的密码缓存，你可以通过<command>svn</command>的<option>--no-auth-cache</option>命令行参数（那些支持这个参数的子命令）来覆盖这个设置，详细信息请见<xref
- linkend="svn-ch-6-sect-2.2"/>。
+ linkend="svn.serverconfig.netmodel.credcache"/>。
</para>
</listitem>
</varlistentry>
@@ -252,20 +248,20 @@
<varlistentry>
<term><literal>editor-cmd</literal></term>
<listitem>
- <para>Subversion在提交操作时用来询问用户日志信息的程序，例如使用<command>svn commit</command>而没有指定<option>--message</option>（<option>-m</option>）或者<option>--file</option>（<option>-F</option>）选项。这个程序也会与<command>svn propedit</command>一起使用—一个临时文件跳出来包含已经存在的用户希望编辑的属性，然后用户可以对这个属性进行编辑（见<xref linkend="svn-ch-7-sect-2" />），这个选项的缺省值为空，如果这个选项没有设置，Subversion会依次检查环境变量<literal>SVN_EDITOR</literal>、<literal>VISUAL</literal>和<literal>EDITOR</literal>（这个顺序）来找到一个编辑器命令。</para>
+ <para>Subversion在提交操作时用来询问用户日志信息的程序，例如使用<command>svn commit</command>而没有指定<option>--message</option>（<option>-m</option>）或者<option>--file</option>（<option>-F</option>）选项。这个程序也会与<command>svn propedit</command>一起使用—一个临时文件跳出来包含已经存在的用户希望编辑的属性，然后用户可以对这个属性进行编辑（见<xref linkend="svn.advanced.props" />），这个选项的缺省值为空，如果这个选项没有设置，Subversion会依次检查环境变量<literal>SVN_EDITOR</literal>、<literal>VISUAL</literal>和<literal>EDITOR</literal>（这个顺序）来找到一个编辑器命令。</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>diff-cmd</literal></term>
<listitem>
- <para>这个命令是比较程序的绝对路径，当Subversion生成了<quote>diff</quote>输出时（例如当使用<command>svn diff</command>命令）就会使用，缺省Subversion会使用一个内置的比较库—设置这个参数会强制它使用外部程序执行这个任务。
+ <para>这个命令是比较程序的绝对路径，当Subversion生成了<quote>diff</quote>输出时（例如当使用<command>svn diff</command>命令）就会使用，缺省Subversion会使用一个内置的比较库—设置这个参数会强制它使用外部程序执行这个任务，此类程序的更多信息见<xref linkend="svn.advanced.externaldifftools"/>。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>diff3-cmd</literal></term>
<listitem>
- <para>这指定了一个三向的比较程序，Subversion使用这个程序来合并用户和从版本库接受的修改，缺省Subversion会使用一个内置的比较库—设置这个参数会导致它会使用外部程序执行这个任务。
+ <para>这指定了一个三向的比较程序，Subversion使用这个程序来合并用户和从版本库接受的修改，缺省Subversion会使用一个内置的比较库—设置这个参数会导致它会使用外部程序执行这个任务，此类程序的更多信息见<xref linkend="svn.advanced.externaldifftools"/>。
</para>
</listitem>
</varlistentry>
@@ -277,7 +273,7 @@
</varlistentry>
</variablelist>
- <para><literal>tunnels</literal>小节允许你定义一个<command>svnserve</command>和<literal>svn://</literal>客户端连接使用的管道模式，更多细节见<xref linkend="svn-ch-6-sect-3.4"/>。</para>
+ <para><literal>tunnels</literal>小节允许你定义一个<command>svnserve</command>和<literal>svn://</literal>客户端连接使用的管道模式，更多细节见<xref linkend="svn.serverconfig.svnserve.sshauth"/>。</para>
<para><literal>miscellany</literal>小节是一些没法归到别处的选项。
<footnote>
@@ -289,9 +285,9 @@
<varlistentry>
<term><literal>global-ignores</literal></term>
<listitem>
- <para>当运行<command>svn status</command>命令时，Subversion会和版本化的文件一样列出未版本化的文件和目录，并使用<literal>?</literal>字符（见see <xref linkend="svn-ch-3-sect-5.3.1" />）标记，有时候察看无关的未版本化文件会很讨厌—比如程序编译产生的对象文件—的显示出来。<literal>global-ignores</literal>选项是一个空格分隔的列表，用来描述Subversion在它们版本化之前不想显示的文件和目录，缺省值是<literal>*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store</literal>。</para>
+ <para>当运行<command>svn status</command>命令时，Subversion会和版本化的文件一样列出未版本化的文件和目录，并使用<literal>?</literal>字符（见see <xref linkend="svn.tour.cycle.examine.status" />）标记，有时候察看无关的未版本化文件会很讨厌—比如程序编译产生的对象文件—的显示出来。<literal>global-ignores</literal>选项是一个空格分隔的列表，用来描述Subversion在它们版本化之前不想显示的文件和目录，缺省值是<literal>*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store</literal>。</para>
- <para>就像<command>svn status</command>，<command>svn add</command>和<command>svn import</command>命令也会忽略匹配这个列表的文件，你可以用单个的<option>--no-ignore</option>命令行参数来覆盖这个选项，关于更加细致的控制忽略的项目，见<xref linkend="svn-ch-7-sect-2.3.3"/>。</para>
+ <para>就像<command>svn status</command>，<command>svn add</command>和<command>svn import</command>命令也会忽略匹配这个列表的文件，你可以用单个的<option>--no-ignore</option>命令行参数来覆盖这个选项，关于更加细致的控制忽略的项目，见<xref linkend="svn.advanced.props.special.ignore"/>。</para>
</listitem>
</varlistentry>
@@ -305,7 +301,7 @@
<varlistentry>
<term><literal>log-encoding</literal></term>
<listitem>
- <para>这个变量设置提交日志缺省的字符集，是<option>--encoding</option>选项（见<xref linkend="svn-ch-9-sect-1.1"/>）的永久形式，Subversion版本库保存了一些UTF8的日志信息，并且假定你的日志信息是用操作系统的本地编码，如果你提交的信息使用别的编码方式，你一定要指定不同的编码。</para>
+ <para>这个变量设置提交日志缺省的字符集，是<option>--encoding</option>选项（见<xref linkend="svn.ref.svn.sw"/>）的永久形式，Subversion版本库保存了一些UTF8的日志信息，并且假定你的日志信息是用操作系统的本地编码，如果你提交的信息使用别的编码方式，你一定要指定不同的编码。</para>
</listitem>
</varlistentry>
@@ -329,10 +325,10 @@
</sect2>
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 2: PROPERTIES *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-7-sect-2">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.props">
<title>属性</title>
<para>我们已经详细讲述了Subversion存储和检索版本库中不同版本的文件和目录的细节，并且用了好几个章节来论述这个工具的基本功能。到此为止，Subversion还仅仅表现出一个普通的版本控制理念。但是Subversion并没有就此止步。</para>
@@ -342,27 +338,27 @@
<sidebar>
<title>Subversion的其他属性</title>
- <para>Subversion的属性也可以在别的地方出现，就像文件和目录可能附加有任意的属性名和值，每个修订版本作为一个整体也可以附加任意的属性，也有同样的限制—可读的文本名称和任何你希望的，二进制值—除了修订版本不是版本化的，参见<xref linkend="svn-ch-5-sect-1.2" />获得版本化的属性信息。</para>
+ <para>Subversion的属性也可以在别的地方出现，就像文件和目录可能附加有任意的属性名和值，每个修订版本作为一个整体也可以附加任意的属性，也有同样的限制—可读的文本名称和任何你希望的，二进制值—除了修订版本不是版本化的，参见<xref linkend="svn.reposadmin.basics.revprops" />获得版本化的属性信息。</para>
</sidebar>
<para>在本小节，我们将会检验这个工具—不仅是对Subversion的用户，也对Subversion本身—对于属性的支持。你会学到与属性相关的<command>svn</command>子命令，和属性怎样影响你的普通Subversion工作流，希望你会感到Subversion的属性可以提高你的版本控制体验。</para>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-2.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.why">
<title>为什么需要属性？</title>
<para>属性可能会是工作拷贝的有益补充，实际上，Subversion本身使用属性来存放特殊的信息，作为支持特别操作的一种方法，同样，你也可以使用属性来实现自己的目的，当然，你对属性作的任何事情也可以针对普通的版本化文件，但是先考虑下面Subversion使用属性的例子。</para>
<para>假定你希望设计一个网站存放许多数码图片，并且显示他们的标题和时间戳，现在你的图片集经常修改，所以你希望你的网站能够尽量的自动化，这些图片可能非常大，所以根据这个网站的特性，你希望在网站给用户提供图标图像。你可以用传统的文件做这件事，你可以有一个<filename>image123.jpg</filename>和一个<filename>image123-thumbnail.jpg</filename>对应在同一个目录，有时候你希望保持文件名相同，你可以使用不同的目录，如<filename>thumbnails/image123.jpg</filename>。你可以用一种相似的样式来保存你的标题和时间戳同原始图像文件分开。很快你的目录树会是一团糟，每个新图片的添加都会成倍的增加混乱。</para>
- <para>现在考虑使用Subversion文件的属性来做相同的设置，想象我们有一个单独的图像文件<filename>image123.jpg</filename>，然后这个文件的属性集包括<literal>caption</literal>、<literal>datestamp</literal>甚至<literal>thumbnail</literal>。现在你的工作拷贝目录看起来更容易管理—实际上，它看起来只有图像文件，但是你的自动化脚本知道得更多，它们知道可以用<command>svn</command>（更好的选择是使用Subversion的语言绑定—见<xref linkend="svn-ch-8-sect-2.3" />）来挖掘更多的站点显示需要的额外信息，而不必去阅读一个索引文件或者是玩一个路径处理的游戏。</para>
+ <para>现在考虑使用Subversion文件的属性来做相同的设置，想象我们有一个单独的图像文件<filename>image123.jpg</filename>，然后这个文件的属性集包括<literal>caption</literal>、<literal>datestamp</literal>甚至<literal>thumbnail</literal>。现在你的工作拷贝目录看起来更容易管理—实际上，它看起来只有图像文件，但是你的自动化脚本知道得更多，它们知道可以用<command>svn</command>（更好的选择是使用Subversion的语言绑定—见<xref linkend="svn.developer.usingapi.otherlangs" />）来挖掘更多的站点显示需要的额外信息，而不必去阅读一个索引文件或者是玩一个路径处理的游戏。</para>
<para>你怎样（而且如果）使用Subversion完全在你，像我们提到的，Subversion拥有它自己的属性集，我们会在后面的章节讨论，但首先，让我们讨论怎样使用<command>svn</command>的属性处理选项。</para>
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-2.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.manip">
<title>处理属性</title>
<para><command>svn</command>命令提供一些方法来添加和修改文件或目录的属性，对于短的，可读的属性，最简单的添加方法是在<command>propset</command>子命令里指定正确的名称和值。</para>
@@ -373,6 +369,18 @@
$
</screen>
+ <para>There are some restrictions on the names you can use for
+ properties. A property name must start with a letter, a colon
+ (<literal>:</literal>), or an underscore
+ (<literal>_</literal>); after that, you can also use digits,
+ hyphens (<literal>-</literal>), and periods
+ (<literal>.</literal>).
+ <footnote>
+ <para>If you're familiar with XML, this is pretty much the
+ ASCII subset of the syntax for XML "Name".</para>
+ </footnote>
+ </para>
+
<para>但是我们已经“吹嘘”过Subversion为属性值提供的灵活性，如果你计划有一个多行的可读文本，甚至是二进制文件的属性值，你通常不希望在命令行里指定，所以<command>propset</command>子命令使用<option>--file</option>（<option>-F</option>）选项来指定一个保存新属性值的文件的名字。</para>
<screen>
@@ -381,7 +389,7 @@
$
</screen>
- <para>作为<command>propset</command>命令的补充，<command>svn</command>提供了一个<command>propedit</command>命令，这个命令使用定制的编辑器程序（见<xref linkend="svn-ch-7-sect-1.3.2" />）来添加和修改属性。当你运行这个命令，<command>svn</command>调用你的编辑器程序打开一个临时文件，文件中保存当前的属性值（或者是空文件，如果你正在添加新的属性）。然后你只需要修改为你想要的值，保存临时文件，然后离开编辑器程序。如果Subversion发现你已经修改了属性值，就会接受新值，如果你未作任何修改而离开，不会产生属性修改操作。</para>
+ <para>作为<command>propset</command>命令的补充，<command>svn</command>提供了一个<command>propedit</command>命令，这个命令使用定制的编辑器程序（见<xref linkend="svn.advanced.confarea.opts.config" />）来添加和修改属性。当你运行这个命令，<command>svn</command>调用你的编辑器程序打开一个临时文件，文件中保存当前的属性值（或者是空文件，如果你正在添加新的属性）。然后你只需要修改为你想要的值，保存临时文件，然后离开编辑器程序。如果Subversion发现你已经修改了属性值，就会接受新值，如果你未作任何修改而离开，不会产生属性修改操作。</para>
<screen>
$ svn propedit copyright calc/button.c ### exit the editor without changes
@@ -470,7 +478,7 @@
$
</screen>
- <para>注意，修改这些未版本化的属性的能力一定要明确的添加给版本库管理员（见<xref linkend="svn-ch-5-sect-2.1" />）。因为属性没有版本化，如果编辑的时候不小心，就会冒丢失信息的风险，版本库管理员可以设置方法来防范这种意外，缺省情况下，修改未版本化的属性是禁止的。</para>
+ <para>注意，修改这些未版本化的属性的能力一定要明确的添加给版本库管理员（见<xref linkend="svn.reposadmin.create.hooks" />）。因为属性没有版本化，如果编辑的时候不小心，就会冒丢失信息的风险，版本库管理员可以设置方法来防范这种意外，缺省情况下，修改未版本化的属性是禁止的。</para>
</sidebar>
@@ -488,7 +496,7 @@
$
</screen>
- <para>注意<command>status</command>子命令显示的<literal>M</literal>在第二列而不是在第一列，这是因为我们修改了<filename>calc/button.c</filename>的属性，而不是它的文本内容，如果我们都修改了，我们也会看到<literal>M</literal>出现在第一列（见<xref linkend="svn-ch-3-sect-5.3.1" />）。</para>
+ <para>注意<command>status</command>子命令显示的<literal>M</literal>在第二列而不是在第一列，这是因为我们修改了<filename>calc/button.c</filename>的属性，而不是它的文本内容，如果我们都修改了，我们也会看到<literal>M</literal>出现在第一列（见<xref linkend="svn.tour.cycle.examine.status" />）。</para>
<sidebar>
<title>属性冲突</title>
@@ -524,14 +532,14 @@
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-2.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.special">
<title>特别属性</title>
<para>Subversion没有关于属性的特殊政策—你可以通过它们实现自己的目的。Subversion只是要求你不要使用<literal>svn:</literal>开头的命名空间作为属性名，这是Subversion自己使用的命名空间。实际上，Subversion定义了某些特殊的属性，这些属性对它们所附加的文件和目录有特殊的影响。在本小节，我们会解开这个谜团，并且描述这些属性怎样让你的生活更加容易。</para>
- <sect3 id="svn-ch-7-sect-2.3.1">
+ <sect3 id="svn.advanced.props.special.executable">
<title><literal>svn:executable</literal></title>
<para><literal>svn:executable</literal>属性用来控制一个版本化的文件自动执行文件权限设定，这个属性没有特定的值—它只是说明一个Subversion可以保留的文件权限的期望值，删除这个属性会恢复操作系统对这些权限的完全控制。</para>
@@ -548,7 +556,7 @@
</sect3>
- <sect3 id="svn-ch-7-sect-2.3.2">
+ <sect3 id="svn.advanced.props.special.mime-type">
<title><literal>svn:mime-type</literal></title>
<para><literal>svn:mime-type</literal>属性为Subversion的许多目的服务，除了保存一个文件的多用途网际邮件扩展（MIME）分类以外，这个属性值也描述了一些Subversion自己使用的行为特性。
@@ -561,10 +569,10 @@
</sect3>
- <sect3 id="svn-ch-7-sect-2.3.3">
+ <sect3 id="svn.advanced.props.special.ignore">
<title><literal>svn:ignore</literal></title>
- <para>这个<literal>svn:ignore</literal>属性保存了一个Subversion特定操作忽略的文件模式列表，或许这个是最常用的属性，它可以与<literal>global-ignores</literal>运行配置选项配合使用（见<xref linkend="svn-ch-7-sect-1.3.2" />）来过滤<command>svn status</command>、<command>svn add</command>和<command>svn import</command>命令中操作的未版本化文件。</para>
+ <para>这个<literal>svn:ignore</literal>属性保存了一个Subversion特定操作忽略的文件模式列表，或许这个是最常用的属性，它可以与<literal>global-ignores</literal>运行配置选项配合使用（见<xref linkend="svn.advanced.confarea.opts.config" />）来过滤<command>svn status</command>、<command>svn add</command>和<command>svn import</command>命令中操作的未版本化文件。</para>
<para><literal>svn:ignore</literal>背后的基本原理很容易解释，Subversion不会假定工作拷贝中的所有文件或子目录是版本控制的一部分，资源必须被显式的使用<command>svn add</command>或者<command>svn import</command>放到Subversion的管理控制之下，作为结果，经常有许多工作拷贝的资源并没有版本化。</para>
@@ -650,7 +658,7 @@
</sect3>
- <sect3 id="svn-ch-7-sect-2.3.4">
+ <sect3 id="svn.advanced.props.special.keywords">
<title><literal>svn:keywords</literal></title>
<para>Subversion具备有添加<firstterm>关键字</firstterm>的能力—一些有用的，关于版本化的文件动态信息的片断—不必直接添加到文件本身。关键字通常会用来描述文件最后一次修改的一些信息，因为这些信息每次都有改变，更重要的一点，这是在文件修改<emphasis>之后</emphasis>，除了版本控制系统，对于任何处理完全保持最新的数据都是一场争论，作为人类作者，信息变得陈旧是不可避免的。</para>
@@ -747,7 +755,7 @@
<para>在你提交了属性修改后，Subversion会立刻更新你的工作文件为新的替代文本，你将无法找到<literal>$LastChangedDate$</literal>的关键字anchor，你会看到替换的结果，这个结果也保存了关键字的名字，与美元符号（<literal>$</literal>）绑定在一起，而且我们预测的，<literal>Rev</literal>关键字不会被替换，因为我们没有要求这样做。</para>
- <para>注意我们设置<literal>svn:keywords</literal>属性为"Date Author"，关键字anchor使用别名<literal>$LastChangedDate$</literal>并且正确的扩展。
+ <para>注意我们设置<literal>svn:keywords</literal>属性为<quote>Date Author</quote>，关键字anchor使用别名<literal>$LastChangedDate$</literal>并且正确的扩展。
</para>
<screen>
@@ -762,7 +770,7 @@
</sect3>
- <sect3 id="svn-ch-7-sect-2.3.5">
+ <sect3 id="svn.advanced.props.special.eol-style">
<title><literal>svn:eol-style</literal></title>
<para>不像我们说过的版本化文件的<literal>svn:mime-type</literal>属性，Subversion假定这个文件保存了可读的数据，一般来讲，Subversion因为这个属性来判断一个文件是否可以用上下文区别报告，否则，对Subversion来说只是字节。</para>
@@ -818,42 +826,632 @@
</sect3>
- <sect3 id="svn-ch-7-sect-2.3.6">
+ <sect3 id="svn.advanced.props.special.externals">
<title><literal>svn:externals</literal></title>
- <para><literal>svn:externals</literal>属性保存了指导Subversion从一个或多个取出的工作拷贝移出目录的指示，关于这个关键字的更多信息，见<xref linkend="svn-ch-7-sect-3"/>。
+ <para><literal>svn:externals</literal>属性保存了指导Subversion从一个或多个取出的工作拷贝移出目录的指示，关于这个关键字的更多信息，见<xref linkend="svn.advanced.externals"/>。
</para>
</sect3>
- <sect3 id="svn-ch-7-sect-2.3.7">
+ <sect3 id="svn.advanced.props.special.special">
<title><literal>svn:special</literal></title>
- <para><literal>svn:special</literal>是唯一一个不是用户直接设置和修改的<literal>svn:</literal>属性，当<quote>特别的</quote>对象如一个对象链接计划加入到版本库，Subversion会自动设置这个属性。版本库像普通文件一样保存<literal>svn:special</literal>对象，然而，当一个客户端在检出和更新操作时看到这个属性时，就会翻译这个文件的内容，并且将文件转化为特殊类型的对象，在Subversion1.1中，只有版本化的符号链接有这个属性附加，但在以后的版本中其它特殊的节点也有可能使用这个属性。</para>
+ <para><literal>svn:special</literal>是唯一一个不是用户直接设置和修改的<literal>svn:</literal>属性，当<quote>特别的</quote>对象如一个对象链接计划加入到版本库，Subversion会自动设置这个属性。版本库像普通文件一样保存<literal>svn:special</literal>对象，然而，当一个客户端在检出和更新操作时看到这个属性时，就会翻译这个文件的内容，并且将文件转化为特殊类型的对象，在Subversion目前的版本中，只有版本化的符号链接有这个属性附加，但在以后的版本中其它特殊的节点也有可能使用这个属性。</para>
<para>注意：Windows客户端不会有符号链接，因此会忽略含有<literal>svn:special</literal>声明为符号链的文件，在Windows，用户会以一个工作拷贝中的版本化的文件作为结束。
</para>
</sect3>
+ <sect3 id="svn.advanced.props.special.needs-lock">
+ <title><literal>svn:needs-lock</literal></title>
+
+ <para>This property is used to signify that the file it's
+ attached to ought to be locked before editing. The value of
+ the property is irrelevant; Subversion will normalize its
+ value to <literal>*</literal>. When present, the file will
+ be read-only <emphasis>unless</emphasis> the user has
+ explicitly locked the file. When a lock-token is present
+ (as a result of running <command>svn lock</command>), the
+ file becomes read-write. When the lock is released, the
+ file becomes read-only again.</para>
+
+ <para>To learn more about how, when, and why this property
+ should be used, see
+ <xref
+ linkend="svn.advanced.locking.lock-communication"/>.</para>
+ </sect3>
+
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-2.4">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.props.auto">
<title>自动属性设置</title>
<para>属性是Subversion一个强大的特性，成为本章和其它章讨论的许多Subversion特性的关键组成部分—文本区别和合并支持、关键字替换、新行的自动转换等等。但是为了从属性得到完全的利益，他们必须设置到正确的文件和目录。不幸的是，在日常工作中很容易忘记这一步工作，特别是当没有设置属性不会引起明显的错误时（至少相对与未能添加一个文件到版本控制这种操作），为了帮助你在需要添加属性的文件上添加属性，Subversion提供了一些简单但是有用的特性。</para>
<para>当你使用<command>svn add</command>或是<command>svn import</command>准备加入一个版本控制的文件时，Subversion会运行一个基本探测来检查文件是包括了可读还是不可读的内容，如果Subversion猜测错误，或者是你希望使用<literal>svn:mime-type</literal>属性更精确的设置—或许是<literal>image/png</literal>或者<literal>application/x-shockwave-flash</literal>—你可以一直删除或编辑那个属性。</para>
- <para>Subversion也提供了自动属性特性，允许你创建文件名到属性名称与值影射，这个影射在你的运行配置区域设置，它们会影响添加和导入操作，而且不仅仅会覆盖Subversion所有缺省的MIME类型判断操作，也会设置额外的Subversion或者自定义的属性。举个例子，你会创建一个影射文件说在任何时候你添加了一个JPEG文件—一些符合<literal>*.jpg</literal>的文件—Subversion一定会自动设置它们的<literal>svn:mime-type</literal>属性为<literal>image/jpeg</literal>。或者是任何匹配<literal>*.cpp</literal>的文件，必须把<literal>svn:eol-style</literal>设置为<literal>native</literal>，并且<literal>svn:keywords</literal>设置为<literal>Id</literal>。自动属性支持是Subversion工具箱中属性相关最垂手可得的工具，见<xref linkend="svn-ch-7-sect-1.3.2"/>来查看更多的配置支持。</para>
+ <para>Subversion也提供了自动属性特性，允许你创建文件名到属性名称与值影射，这个影射在你的运行配置区域设置，它们会影响添加和导入操作，而且不仅仅会覆盖Subversion所有缺省的MIME类型判断操作，也会设置额外的Subversion或者自定义的属性。举个例子，你会创建一个影射文件说在任何时候你添加了一个JPEG文件—一些符合<literal>*.jpg</literal>的文件—Subversion一定会自动设置它们的<literal>svn:mime-type</literal>属性为<literal>image/jpeg</literal>。或者是任何匹配<literal>*.cpp</literal>的文件，必须把<literal>svn:eol-style</literal>设置为<literal>native</literal>，并且<literal>svn:keywords</literal>设置为<literal>Id</literal>。自动属性支持是Subversion工具箱中属性相关最垂手可得的工具，见<xref linkend="svn.advanced.confarea.opts.config"/>来查看更多的配置支持。</para>
</sect2>
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 2 1/2: PEG AND OPERATIVE REVISIONS *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-7-sect-2b">
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.locking">
+ <title>Locking</title>
+
+ <para>Subversion's <quote>copy-modify-merge</quote> model is
+ optimal when users are collaborating on projects that consist of
+ line-based text files, such as program source code. However, as
+ discussed in <xref
+ linkend="svn.basic.vsn-models.copy-merge.sb-1"/>, sometimes one
+ has to use the <quote>lock-modify-unlock</quote> model instead
+ of Subversion's standard concurrent model. When a file consists
+ of binary data, it's often difficult or impossible to merge two
+ sets of changes made in parallel by different users. For this
+ reason, Subversion 1.2 and later offers a feature known as
+ <firstterm>locking</firstterm>, often known as <quote>reserved
+ checkouts</quote> in other version control systems.</para>
+
+ <para>Subversion's locking feature has two main goals:</para>
+
+ <itemizedlist>
+ <listitem><para><emphasis>Serializing access to a
+ resource</emphasis>. Allow a user to grab an exclusive
+ right to change to a file in the repository. If Harry
+ reserves the right to change <filename>foo.jpg</filename>,
+ then Sally should not be able to commit a change to it.</para>
+ </listitem>
+ <listitem><para><emphasis>Aiding communication</emphasis>.
+ Prevent users from wasting time on unmergeable changes. If
+ Harry has reserved the right to change
+ <filename>foo.jpg</filename>, then it should be easy for
+ Sally to notice this fact and avoid working on the
+ file.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Subversion's locking feature is currently limited to files
+ only—it's not yet possible to reserve access to a whole
+ directory tree.</para>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.locking.creation">
+ <title>Creating locks</title>
+
+ <para>In the Subversion repository, a
+ <firstterm>lock</firstterm> is a piece of metadata which
+ grants exclusive access to one user to change a file. This
+ user is said to be the <firstterm>lock owner</firstterm>.
+ Each lock also has a unique identifier, typically a long
+ string of characters, known as the <firstterm>lock
+ token</firstterm>. The repository manages locks in a separate
+ table, and enforces locks during a commit operation. If any
+ commit transaction attempts to modify or delete the file (or
+ delete a parent of the file), the repository will demand two
+ pieces of information:</para>
+
+ <orderedlist>
+ <listitem><para><emphasis role="bold">User
+ authentication</emphasis>. The client performing the commit
+ must be authenticated as the lock owner.</para>
+ </listitem>
+ <listitem><para><emphasis role="bold">Software
+ authorization</emphasis>. The user's working copy must send
+ the lock token with the commit, proving that it knows
+ exactly which lock it's using.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>An example is in order, to demonstrate. Let's say that
+ Harry has decided to change a JPEG image. To prevent other
+ people from committing changes to the file, he locks the file
+ in the repository using the <command>svn lock</command>
+ command:</para>
+
+ <screen>
+$ svn lock banana.jpg --message "Editing file for tomorrow's release."
+'banana.jpg' locked by user 'harry'.
+
+$ svn status
+ K banana.jpg
+
+$ svn info banana.jpg
+Path: banana.jpg
+Name: banana.jpg
+URL: http://svn.example.com/repos/project/banana.jpg
+Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
+Revision: 2198
+Node Kind: file
+Schedule: normal
+Last Changed Author: frank
+Last Changed Rev: 1950
+Last Changed Date: 2005-03-15 12:43:04 -0600 (Tue, 15 Mar 2005)
+Text Last Updated: 2005-06-08 19:23:07 -0500 (Wed, 08 Jun 2005)
+Properties Last Updated: 2005-06-08 19:23:07 -0500 (Wed, 08 Jun 2005)
+Checksum: 3b110d3b10638f5d1f4fe0f436a5a2a5
+Lock Token: opaquelocktoken:0c0f600b-88f9-0310-9e48-355b44d4a58e
+Lock Owner: harry
+Lock Created: 2005-06-14 17:20:31 -0500 (Tue, 14 Jun 2005)
+Lock Comment (1 line):
+Editing file for tomorrow's release.
+
+</screen>
+
+ <para>There are a number of new things demonstrated in the
+ previous example. First, notice that Harry passed the
+ <option>--message</option> option to <command>svn
+ lock</command>. Similar to <command>svn commit</command>,
+ the <command>svn lock</command> command can take comments
+ (either via
+ <option>--message (-m)</option> or <option>--file
+ (-F)</option>) to describe the reason for locking the file.
+ Unlike <command>svn commit</command>, however, <command>svn
+ lock</command> will not demand a message by launching your
+ preferred text editor. Lock comments are optional, but still
+ recommended to aid communication.</para>
+
+ <para>Second, the lock attempt succeeded. This means that the
+ file wasn't already locked, and that Harry had the latest
+ version of the file. If Harry's working copy of the file had
+ been out-of-date, the repository would have rejected the
+ request, forcing harry to <command>svn update</command> and
+ reattempt the locking command.</para>
+
+ <para>Also notice that after creating the lock in the
+ repository, the working copy has cached information about the
+ lock—most importantly, the lock token. The presence of
+ the lock token is critical. It gives the working copy
+ authorization to make use of the lock later on. The
+ <command>svn status</command> command shows a
+ <literal>K</literal> next to the file (short for locKed),
+ indicating that the lock token is present.</para>
+
+ <sidebar>
+ <title>Regarding lock tokens</title>
+
+ <para>A lock token isn't an authentication token, so much as
+ an <emphasis>authorization</emphasis> token. The token
+ isn't a protected secret. In fact, a lock's unique token is
+ discoverable by anyone who runs <command>svn info
+ URL</command>.</para>
+
+ <para>A lock token is special only when it lives inside a
+ working copy. It's proof that the lock was created in that
+ particular working copy, and not somewhere else by some
+ other client. Merely authenticating as the lock owner isn't
+ enough to prevent accidents.</para>
+
+ <para>For example: suppose you lock a file using a computer at
+ your office, perhaps as part of a changeset in progress. It
+ should not be possible for a working copy (or alternate
+ Subversion client) on your home computer to accidentally
+ commit a change to that same file, just because you've
+ authenticated as the lock's owner. In other words, the lock
+ token prevents one piece of Subversion-related software from
+ undermining the work of another. (In our example, if you
+ really need to change the file from an alternate working
+ copy, you would need to break the lock and re-lock the
+ file.)</para>
+ </sidebar>
+
+ <para>Now that Harry has locked <filename>banana.jpg</filename>,
+ Sally is unable to change or delete that file:</para>
+
+ <screen>
+$ whoami
+sally
+
+$ svn delete banana.jpg
+D banana.jpg
+
+$ svn commit -m "Delete useless file."
+Deleting banana.jpg
+svn: Commit failed (details follow):
+svn: DELETE of
+'/repos/project/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/banana.jpg':
+423 Locked (http://svn.example.com)
+
+</screen>
+
+ <para>But Harry, after touching up the banana's shade of yellow,
+ is able to commit his changes to the file. That's because he
+ authenticates as the lock owner, and also because his working
+ copy holds the correct lock token:</para>
+
+ <screen>
+$ whoami
+harry
+
+$ svn status
+M K banana.jpg
+
+$ svn commit -m "Make banana more yellow"
+Sending banana.jpg
+Transmitting file data .
+Committed revision 2201.
+
+$ svn status
+$
+</screen>
+
+ <para>Notice that after the commit is finished, <command>svn
+ status</command> shows that the lock token is no longer
+ present in working copy. This is the standard behavior
+ of <command>svn commit</command>: it walks the working copy
+ (or list of targets, if you provide such a list), and sends
+ all lock tokens it encounters to the server as part of the
+ commit transaction. After the commit completes
+ successfully, all of the repository locks that were
+ mentioned are released—<emphasis>even on files that
+ weren't committed.</emphasis> The rationale here is to
+ discourage users from being sloppy about locking, or from
+ holding locks for too long. For example, suppose Harry were
+ to haphazardly lock thirty files in a directory named
+ <filename>images</filename>, because he's unsure of which
+ files he needs to change. He ends up making changes to only
+ four files. When he runs <command>svn commit
+ images</command>, the process would still release all thirty
+ locks.</para>
+
+ <para>This behavior of automatically releasing locks can be
+ overridden with the <option>--no-unlock</option> option
+ to <command>svn commit</command>. This is best used for
+ those times when you want to commit changes, but still plan
+ to make more changes and thus need to retain existing locks.
+ This behavior is also semi-permanently tweakable, by setting
+ <literal>no-unlock = yes</literal> in your run-time
+ <filename>config</filename> file (see <xref
+ linkend="svn.advanced.confarea"/>.)</para>
+
+ <para>Of course, locking a file doesn't oblige one to commit a
+ change to it. The lock can be released at any time with a
+ simple
+ <command>svn unlock</command> command:</para>
+
+ <screen>
+$ svn unlock banana.c
+'banana.c' unlocked.
+</screen>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.locking.discovery">
+ <title>Discovering locks</title>
+
+ <para>When a commit fails due to someone else's locks, it's
+ fairly easy to learn about them. The easiest of
+ these is <command>svn status --show-updates</command>:</para>
+
+ <screen>
+$ whoami
+sally
+
+$ svn status --show-updates
+M 23 bar.c
+M O 32 raisin.jpg
+ * 72 foo.h
+Status against revision: 105
+</screen>
+
+ <para>In this example, Sally can see not only that her copy of
+ <filename>foo.h</filename> is out-of-date, but that one of the
+ two modified files she plans to commit is locked in the
+ repository. The <literal>O</literal> symbol stands for
+ <quote>Other</quote>, meaning that a lock exists on the file,
+ and was created by somebody else. If she were to attempt a
+ commit, the lock on <filename>raisin.jpg</filename> would
+ prevent it. Sally is left wondering who made the lock, when,
+ and why. Once again, <command>svn info</command> has the
+ answers:</para>
+
+ <screen>
+$ svn info http://svn.example.com/repos/project/raisin.jpg
+Path: raisin.jpg
+Name: raisin.jpg
+URL: http://svn.example.com/repos/project/raisin.jpg
+Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
+Revision: 105
+Node Kind: file
+Last Changed Author: sally
+Last Changed Rev: 32
+Last Changed Date: 2005-01-25 12:43:04 -0600 (Tue, 25 Jan 2005)
+Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
+Lock Owner: harry
+Lock Created: 2005-02-16 13:29:18 -0500 (Wed, 16 Feb 2005)
+Lock Comment (1 line):
+Need to make a quick tweak to this image.
+</screen>
+
+ <para>Just as <command>svn info</command> can be used to examine
+ objects in the working copy, it can also be used to examine
+ objects in the repository. If the main argument to
+ <command>svn info</command> is a working copy path, then all
+ of the working copy's cached information is displayed; any
+ mention of a lock means that the working copy is holding a
+ lock token (if a file is locked by another user or in another
+ working copy, <command>svn info</command> on a working copy
+ path will show no lock information at all). If the main
+ argument to <command>svn info</command> is a URL, then the
+ information reflects the latest version of an object in the
+ repository; any mention of a lock describes the current lock
+ on the object.</para>
+
+ <para>So in this particular example, Sally can see that Harry
+ locked the file on February 16th to <quote>make a quick
+ tweak</quote>. It being June, she suspects that he probably
+ forgot all about the lock. She might phone Harry to complain
+ and ask him to release the lock. If he's unavailable, she
+ might try to forcibly break the lock herself or ask an
+ administrator to do so.</para>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.locking.break-steal">
+ <title>Breaking and stealing locks</title>
+
+ <para>A repository lock isn't sacred; it can be released not
+ only by the person who created it, but by anyone at all. When
+ somebody other than the original lock creator destroys a lock,
+ we refer to this as <firstterm>breaking</firstterm> the
+ lock.</para>
+
+ <para>From the administrator's chair, it's simple to break
+ locks. The <command>svnlook</command>
+ and <command>svnadmin</command> programs have the ability to
+ display and remove locks directly from the repository. (For
+ more information about these tools, see
+ <xref linkend="svn.reposadmin.maint.tk"/>.)</para>
+
+ <screen>
+$ svnadmin lslocks /usr/local/svn/repos
+Path: /project2/images/banana.jpg
+UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923
+Owner: frank
+Created: 2005-06-15 13:29:18 -0500 (Wed, 15 Jun 2005)
+Expires:
+Comment (1 line):
+Still improving the yellow color.
+
+Path: /project/raisin.jpg
+UUID Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
+Owner: harry
+Created: 2005-02-16 13:29:18 -0500 (Wed, 16 Feb 2005)
+Expires:
+Comment (1 line):
+Need to make a quick tweak to this image.
+
+$ svnadmin rmlocks /usr/local/svn/repos /project/raisin.jpg
+Removed lock on '/project/raisin.jpg'.
+</screen>
+
+ <para>The more interesting option is allowing users to break
+ each other's locks over the network. To do this, one simply
+ needs to pass the <option>--force</option> to the unlock
+ command:</para>
+
+ <screen>
+$ whoami
+sally
+
+$ svn status --show-updates
+M 23 bar.c
+M O 32 raisin.jpg
+ * 72 foo.h
+Status against revision: 105
+
+$ svn unlock raisin.jpg
+svn: 'raisin.jpg' is not locked in this working copy
+
+$ svn info raisin.jpg | grep URL
+URL: http://svn.example.com/repos/project/raisin.jpg
+
+$ svn unlock http://svn.example.com/repos/project/raisin.jpg
+svn: Unlock request failed: 403 Forbidden (http://svn.example.com)
+
+$ svn unlock --force http://svn.example.com/repos/project/raisin.jpg
+'raisin.jpg' unlocked.
+</screen>
+
+ <para>Sally's initial attempt to unlock failed because she
+ ran <command>svn unlock</command> directly on her working copy
+ of the file, and no lock token was present. To remove the
+ lock directly from the repository, she needs to pass a URL
+ to <command>svn unlock</command>. Her first attempt to unlock
+ the URL fails, because she can't authenticate as the lock
+ owner (nor does she have the lock token). But when she
+ passes <option>--force</option>, the authentication and
+ authorization requirements are ignored, and the remote lock is
+ broken.</para>
+
+ <para>Of course, simply breaking a lock may not be enough. In
+ the running example, Sally may not only want to break Harry's
+ long-forgotten lock, but re-lock the file for her own use.
+ She can accomplish this by running <command>svn unlock
+ --force</command> and then <command>svn lock</command>
+ back-to-back, but there's a small chance that somebody else
+ might lock the file between the two commands. The simpler thing
+ to is <firstterm>steal</firstterm> the lock, which involves
+ breaking and re-locking the file all in one atomic step. To
+ do this, pass the <option>--force</option> option
+ to <command>svn lock</command>:</para>
+
+ <screen>
+$ svn lock raisin.jpg
+svn: Lock request failed: 423 Locked (http://svn.example.com)
+
+$ svn lock --force raisin.jpg
+'raisin.jpg' locked by user 'sally'.
+</screen>
+
+ <para>In any case, whether the lock is broken or stolen, Harry
+ may be in for a surprise. Harry's working copy still
+ contains the original lock token, but that lock no longer
+ exists. The lock token is said to
+ be <firstterm>defunct</firstterm>. The lock represented by
+ the lock-token has either been broken (no longer in the
+ repository), or stolen (replaced with a different lock).
+ Either way, Harry can see this by asking <command>svn
+ status</command> to contact the repository:</para>
+
+ <screen>
+$ whoami
+harry
+
+$ svn status
+ K raisin.jpg
+
+$ svn status --show-updates
+ B 32 raisin.jpg
+
+$ svn update
+ B raisin.jpg
+
+$ svn status
+
+$
+</screen>
+
+ <para>If the repository lock was broken, then <command>svn
+ status --show-updates</command> displays
+ a <literal>B</literal> (Broken) symbol next to the file.
+ If a new lock exists in place of the old one, then
+ a <literal>T</literal> (sTolen) symbol is shown.
+ Finally, <command>svn update</command> notices any defunct
+ lock tokens and removes them from the working copy.</para>
+
+ <sidebar>
+ <title>Locking Policies</title>
+
+ <para>Different systems have different notions of how strict
+ a lock should be. Some folks argue that locks must be
+ strictly enforced at all costs, releasable only by the
+ original creator or administrator. They argue that if
+ anyone can break a lock, then chaos breaks loose and the
+ whole point of locking is defeated. The other side argues
+ that locks are first and foremost a communication tool.
+ If users are constantly breaking each others' locks, then
+ it represents a cultural failure within the team and the
+ problem falls outside the scope of software
+ enforcement.</para>
+
+ <para>Subversion defaults to the <quote>softer</quote>
+ approach, but still allows administrators to create
+ stricter enforcement policies through the use of hook
+ scripts. In particular, the <filename>pre-lock</filename>
+ and <filename>pre-unlock</filename> hooks allow
+ administrators to decide when lock creation and lock
+ releases are allowed to happen. Depending on whether or
+ not a lock already exists, these two hooks can decide
+ whether or not to allow a certain user to break or steal a
+ lock. The <filename>post-lock</filename>
+ and <filename>post-unlock</filename> hooks are also
+ available, and can be used to send email after locking
+ actions.</para>
+
+ <para>To learn more about repository hooks, see
+ <xref linkend="svn.reposadmin.create.hooks"/>.</para>
+ </sidebar>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.locking.lock-communication">
+ <title>Lock Communication</title>
+
+ <para>We've seen how <command>svn lock</command>
+ and <command>svn unlock</command> can be used to create,
+ release, break, and steal locks. This satisfies the goal of
+ serializing commit access to a file. But what about the
+ larger problem of preventing wasted time?</para>
+
+ <para>For example, suppose Harry locks an image file and then
+ begins editing it. Meanwhile, miles away, Sally wants to do
+ the same thing. She doesn't think to run <command>svn status
+ --show-updates</command>, so she has no idea that Harry has
+ already locked the file. She spends hours editing the file,
+ and when she tries to commit her change, she discovers that
+ either the file is locked or that she's out-of-date.
+ Regardless, her changes aren't mergeable with Harry's. One of
+ these two people has to throw away their work, and a lot of
+ time has been wasted.</para>
+
+ <para>Subversion's solution to this problem is provide a
+ mechanism to remind users that a file ought to be locked
+ <emphasis>before</emphasis> the editing begins.</para>
+
+ <para>The mechanism is a special
+ property, <literal>svn:needs-lock</literal>. If the property
+ is attached to a file (the value is irrelevant), then the file
+ will have read-only permissions. When the user locks the file
+ and receives a lock token, the file becomes read-write. When
+ the lock is released—either explicitly unlocked, or
+ released via commit—the file returns to read-only
+ again.</para>
+
+ <para>The theory, then, is that if the image file has this
+ property attached, then Sally would immediately notice
+ something is strange when she opens the file for editing. Her
+ application would be unable to save changes, or (better yet)
+ tell her that the file is read-only. This reminds her to lock
+ the file before editing, whereby she discovers the
+ pre-existing lock:</para>
+
+ <screen>
+$ /usr/local/bin/gimp raisin.jpg
+gimp: error: file is read-only!
+
+$ ls -l raisin.jpg
+-r--r--r-- 1 sally sally 215589 Jun 8 19:23 raisin.jpg
+
+$ svn lock raisin.jpg
+svn: Lock request failed: 423 Locked (http://svn.example.com)
+
+$ svn info http://svn.example.com/repos/project/raisin.jpg | grep Lock
+Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
+Lock Owner: harry
+Lock Created: 2005-06-08 07:29:18 -0500 (Thu, 08 June 2005)
+Lock Comment (1 line):
+Making some tweaks. Locking for the next two hours.
+
+</screen>
+
+ <para>As a matter of <quote>best practice</quote>, both users
+ and administrators are encouraged to attach
+ the <literal>svn:needs-lock</literal> property to any file
+ which cannot be contextually merged. It's the main
+ technique for encouraging good locking habits and preventing
+ wasted effort.</para>
+
+ <para>Note that this property is a communication tool which
+ works independently from the locking system. In other
+ words, any file can be locked, whether or not this property
+ is present. And conversely, the presence of this property
+ doesn't make the repository require a lock when
+ committing.</para>
+
+ <para>The system isn't flawless, either. It's possible that
+ even when a file has the property, the read-only reminder
+ won't always work. Sometimes applications misbehave and
+ <quote>hijack</quote> the read-only file, silently allowing
+ users to edit and save the file anyway. Unfortunately,
+ there's not much Subversion can do about this.</para>
+
+ </sect2>
+
+ </sect1>
+
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.pegrevs">
<title>Peg和实施修订版本</title>
<para>文件和目录的拷贝、移动和改名能力可以让我们可以删除一个对象，然后在同样的路径添加一个新的—这是我们在电脑上对文件和目录经常作的操作，我们认为这些操作都是理所当然的。Subversion很乐意你认为这些操作已经赋予给你，Subversion的文件管理操作是这样的解放，提供了几乎和普通文件一样的操作版本化文件的灵活性，但是灵活意味着在整个版本库的生命周期中，一个给定的版本化的资源可能会出现在许多不同的路径，一个给定的路径会展示给我们许多完全不同的版本化资源。</para>
@@ -886,7 +1484,45 @@
我们可以把<quote>主大道</quote>看作路径，把<quote>惠顿</quote>当作我们的peg修订版本。这两段信息确认了我们可以旅行（主大道的北方或南方）的唯一路径，也会保持我们不会在前前后后寻找目标时走到错误的主大道。现在我们把<quote>606 N.</quote>作为我们实施的修订版本，我们<emphasis>精确的</emphasis>知道到哪里。
</para>
- <para>当使用peg和实施修订版本来查找我们需要工作文件时，Subversion会执行一个很直接的算法。首先，找到与peg修订版本相关的路径坐落于版本库的那个修订版本，Subversion开始从那里开始向后查询这个对象的历史前辈。每个前辈表示这个对象的以前的一个版本，每一个版本的对象都保存了自己被创建的修订版本和路径，所以通过前辈集，Subversion可以注意到哪个版本是这个实施修订版本最年轻的版本，如果是，可以将实施修订版本影射到前辈创建的路径/创建修订版本对。算法在所有的实施修订版本影射到真实的对象位置后，或者是没有更多的前辈时完成，就是任何未影射的实施修订版本已经标记为不符合操作的对象。</para>
+ <sidebar>
+ <title>The "peg-revision" algorithm</title>
+
+ <para>When the commandline client sees a command of the
+ form:</para>
+
+ <screen>
+$ svn <replaceable>command</replaceable> -r <replaceable>OPERATIVE-REV</replaceable> item@<replaceable>PEG-REV</replaceable>
+</screen>
+
+ <para>...it performs the following algorithm:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>Go to revision <replaceable>PEG-REV</replaceable>, and
+ find <replaceable>item</replaceable>. This locates a unique
+ object in the repository.</para>
+ </listitem>
+
+ <listitem>
+ <para>Trace the object's history backwards (through any
+ possible renames) to its ancestor in
+ revision <replaceable>OPERATIVE-REV</replaceable>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Perform the requested action on that ancestor,
+ wherever it is located, or whatever its name might
+ be.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>Remember that even when you don't explicitly supply a
+ peg-revision, it's still present. It defaults to BASE for
+ working copy items, and to HEAD for URLs.</para>
+
+ </sidebar>
<para>也就是说很久以前我们创建了我们的版本库，在修订版本1添加我们第一个<filename>concept</filename>目录，并且在这个目录增加一个<filename>IDEA</filename>文件与concept相关，在几个修订版本之后，真实的代码被添加和修改，我们在修订版本20，修改这个目录为<filename>frabnaggilywort</filename>。通过修订版本27，我们有了一个新的概念，所以一个新的<filename>concept</filename>目录用来保存这些东西，一个新的<filename>IDEA</filename>文件来描述这个概念，然后经过5年20000个修订版本，就像他们都有一个非常浪漫的历史。
</para>
@@ -960,16 +1596,16 @@
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 3: EXTERNALS DEFINITIONS *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-7-sect-3">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.externals">
<title>外部定义</title>
<para>有时候创建一个由多个不同检出得到的工作拷贝是非常有用的，举个例子，你或许希望不同的子目录来自不同的版本库位置，或者是不同的版本库。你可以手工设置这样一个工作拷贝—使用<command>svn checkout</command>来创建这种你需要的嵌套的工作拷贝结构。但是如果这个结构对所有的用户是很重要的，每个用户需要执行同样的检出操作。</para>
<para>很幸运，Subversion提供了<firstterm>外部定义</firstterm>的支持，一个外部定义是一个本地路经到URL的影射—也有可能一个特定的修订版本—一些版本化的资源。在Subversion你可以使用<literal>svn:externals</literal>属性来定义外部定义，你可以用<command>svn propset</command>或<command>svn
- propedit</command>（见<xref linkend="svn-ch-7-sect-2.1"/>）创建和修改这个属性。它可以设置到任何版本化的路经，它的值是一个多行的子目录和完全有效的Subversion版本库URL的列表（相对于设置属性的版本化目录）。
+ propedit</command>（见<xref linkend="svn.advanced.props.why"/>）创建和修改这个属性。它可以设置到任何版本化的路经，它的值是一个多行的子目录和完全有效的Subversion版本库URL的列表（相对于设置属性的版本化目录）。
</para>
<screen>
@@ -1008,23 +1644,47 @@
<para><command>svn status</command>命令也认识外部定义，会为外部定义的子目录显示<literal>X</literal>状态码，然后迭代这些子目录来显示外部项目的子目录状态信息。</para>
+<tip>
+ <para>You should strongly consider using explicit revision
+ numbers in all of your externals definitions. Doing so means
+ that you get to decide when to pull down a different snapshot
+ of external information, and exactly which snapshot to pull.
+ Besides the common sense aspect of not being surprised by
+ changes to third-party repositories that you might not have
+ any control over, using explicit revision numbers also means
+ that as you backdate your working copy to a previous
+ revision, your externals definitions will also revert to the
+ way they looked in that previous revision, which in turn means
+ that the external working copies will be updated to match they
+ way <emphasis>they</emphasis> looked back when your repository was
+ at that previous revision. For software projects, this could
+ be the difference between a successful and a failed build of
+ an older snapshot of your complex codebase.</para>
+ </tip>
<para>Subversion目前对外部定义的支持可能会引起误导，首先，一个外部定义只可以指向目录，而不是文件。第二，外部定义不可以指向相对路径（如<filename>../../skins/myskin</filename>）。第三，同过外部定义创建的工作拷贝与主工作拷贝没有连接，所以举个例子，如果你希望提交一个或多个外部定义的拷贝，你必须在这些工作拷贝显示的运行<command>svn commit</command>—对主工作拷贝的提交不会迭代到外部定义的部分。</para>
<para>另外，因为定义本身使用绝对路径，移动和拷贝路径他们附着的路径不会影响他们作为外部的检出（尽管相对的本地目标子目录会这样，当然，根据重命名的目录）。这看起来有些迷惑—甚至让人沮丧—在特定情形。举个例子，如果你在<filename>/trunk</filename>开发线对一个目录使用外部定义，指向同一条线上的其他区域，然后使用<command>svn copy</command>把分支开发线拷贝到<filename>/branches/my-branch</filename>这个新位置，这个项目新分支的外部定义仍然指向<filename>/trunk</filename>版本化资源。另外，需要意识到如果你需要一个重新规划你的工作拷贝的父目录（使用<command>svn switch --relocate</command>），外部定义<emphasis>不</emphasis>会重新选择父目录。</para>
+ <para>Finally, there might be times when you would prefer that
+ <command>svn</command> subcommands would not recognize or
+ otherwise operate on the external working copies created as the
+ result of externals definition handling. In those instances,
+ you can pass the <option>--ignore-externals</option> option to
+ the subcommand.</para>
+
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 4: VENDOR BRANCHES *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-7-sect-4">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.vendorbr">
<title>卖主分支</title>
<para>当开发软件时有这样一个情况，你版本控制的数据可能关联于或者是依赖于其他人的数据，通常来讲，你的项目的需要会要求你自己的项目对外部实体提供的数据保持尽可能最新的版本，同时不会牺牲稳定性，这种情况总是会出现—只要某个小组的信息对另一个小组的信息有直接的影响。</para>
- <para>举个例子，软件开发者会工作在一个使用第三方库的应用，Subversion恰好是和Apache的Portable Runtime library（见<xref linkend="svn-ch-8-sect-2.1" />）有这样一个关系。Subversion源代码依赖于APR库来实现可移植需求。在Subversion的早期开发阶段，项目紧密地追踪APR的API修改，经常在库代码的<quote>流血的边缘</quote>粘住，现在APR和Subversion都已经成熟了，Subversion只尝试同步APR的经过良好测试的，稳定的API库。</para>
+ <para>举个例子，软件开发者会工作在一个使用第三方库的应用，Subversion恰好是和Apache的Portable Runtime library（见<xref linkend="svn.developer.usingapi.apr" />）有这样一个关系。Subversion源代码依赖于APR库来实现可移植需求。在Subversion的早期开发阶段，项目紧密地追踪APR的API修改，经常在库代码的<quote>流血的边缘</quote>粘住，现在APR和Subversion都已经成熟了，Subversion只尝试同步APR的经过良好测试的，稳定的API库。</para>
- <para>现在，如果你的项目依赖于其他人的信息，有许多方法可以用来尝试同步你的信息，最痛苦的，你可以为项目所有的贡献者发布口头或书写的指导，告诉他们确信他们拥有你们的项目需要的特定版本的第三方信息。如果第三方信息是用Subversion版本库维护，你可以使用Subversion的外部定义来有效的<quote>强制</quote>特定的版本的信息在你的工作拷贝的的位置（见<xref linkend="svn-ch-7-sect-3" />）。</para>
+ <para>现在，如果你的项目依赖于其他人的信息，有许多方法可以用来尝试同步你的信息，最痛苦的，你可以为项目所有的贡献者发布口头或书写的指导，告诉他们确信他们拥有你们的项目需要的特定版本的第三方信息。如果第三方信息是用Subversion版本库维护，你可以使用Subversion的外部定义来有效的<quote>强制</quote>特定的版本的信息在你的工作拷贝的的位置（见<xref linkend="svn.advanced.externals" />）。</para>
<para>但是有时候，你希望在你自己的版本控制系统维护一个针对第三方数据的自定义修改，回到软件开发的例子，程序员为了他们自己的目的会需要修改第三方库，这些修改会包括新的功能和bug修正，在成为第三方工具官方发布之前，只是内部维护。或者这些修改永远不会传给库的维护者，只是作为满足软件开发需要的单独的自定义修改存在。</para>
@@ -1034,8 +1694,8 @@
<para>卖主分支提供了两个关键的益处，第一，通过在我们的版本控制系统保存现在支持的卖主drop，你项目的成员不需要指导他们是否有了正确版本的卖主数据，他们只需要作为不同工作拷贝更新的一部份，简单的接受正确的版本就可以了。第二，因为数据存在于你自己的Subversion版本库，你可以在恰当的位置保存你的自定义修改—你不需要一个自动的（或者是更坏，手工的）方法来交换你的自定义行为。</para>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-4.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.vendorbr.general">
<title>常规的卖主分支管理过程</title>
<para>管理卖主分支通常会像这个样子，你创建一个顶级的目录（如<filename>/vendor</filename>）来保存卖主分支，然后你导入第三方的代码到你的子目录。然后你将拷贝这个子目录到主要的开发分支（例如<filename>/trunk</filename>）的适当位置。你一直在你的主要开发分支上做本地修改，当你的追踪的代码有了新版本，你会把带到卖主分支并且把它合并到你的<filename>/trunk</filename>，解决任何你的本地修改和他们的修改的冲突。</para>
@@ -1049,7 +1709,7 @@
…
</screen>
- <para>我们现在在<filename>/vendor/libcomplex/current</filename>有了libcomplex当前版本的代码，现在我们为那个版本作标签（见<xref linkend="svn-ch-4-sect-6" />），然后拷贝它到主要开发分支，我们的拷贝会在<filename>calc</filename>项目目录创建一个新的目录<filename>libcomplex</filename>，它是这个我们将要进行自定义的卖主数据的拷贝版本。</para>
+ <para>我们现在在<filename>/vendor/libcomplex/current</filename>有了libcomplex当前版本的代码，现在我们为那个版本作标签（见<xref linkend="svn.branchmerge.tags" />），然后拷贝它到主要开发分支，我们的拷贝会在<filename>calc</filename>项目目录创建一个新的目录<filename>libcomplex</filename>，它是这个我们将要进行自定义的卖主数据的拷贝版本。</para>
<screen>
$ svn copy http://svn.example.com/repos/vendor/libcomplex/current \
@@ -1098,8 +1758,8 @@
another section on bypassing svn_load_dirs.pl altogether and
running with just svn merge, now that it ignores ancestry. -->
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-7-sect-4.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.vendorbr.svn_load_dirs">
<title><command>svn_load_dirs.pl</command></title>
<para>不仅仅包含一些删除、添加和移动的卖主drops使得升级第三方数据后续版本的过程变得复杂，所以Subversion提供了一个<command>svn_load_dirs.pl</command>脚本来辅助这个过程，这个脚本自动进行我们前面提到的常规卖主分支管理过程的导入步骤，从而使得错误最小化。你仍要负责使用合并命令合并第三方的新
@@ -1160,15 +1820,16 @@
</sect2>
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 5: LOCALIZATION *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-7-sect-5">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.l10n">
<title>本地化</title>
<para><firstterm>本地化</firstterm>是让程序按照地区特定方式运行的行为，如果一个程序的格式、数字或者是日期是你的本地方式，或者是打印的信息（或者是接受的输入）是你本地的语言，这个程序被叫做已经<firstterm>本地化了</firstterm>，这部分描述了针对本地化的Subversion的步骤。</para>
- <sect2 id="svn-ch7-sect-5.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.l10n.understanding">
<title>理解地区</title>
<para>许多现代操作系统都有一个<quote>当前地区</quote>的概念—也就是本地化习惯服务的国家和地区。这些习惯—通常是被一些运行配置机制选择—影响程序展现数据的方式，也有接受用户输入的方式。</para>
@@ -1193,7 +1854,8 @@
</sect2>
- <sect2 id="svn-ch7-sect-5.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.l10n.svnuse">
<title>Subversion对地区的支持</title>
<para>Subversion客户端，<command>svn</command>通过两种方式支持当前的地区配置。首先，它会注意<literal>LC_MESSAGES</literal>的值，然后尝试使用特定的语言打印所有的信息，例如：</para>
@@ -1201,8 +1863,8 @@
<screen>
$ export LC_MESSAGES=de_DE
$ svn help cat
-cat: Ausgabe des Inhaltes der angegebenen Dateien oder URLs
-Aufruf: cat ZIEL...
+cat: Gibt den Inhalt der angegebenen Dateien oder URLs aus.
+Aufruf: cat ZIEL[@REV]...
…
</screen>
@@ -1220,10 +1882,13 @@
<para>当使用Subversion，你或许会碰到一个字符集转化关联的错误：</para>
<screen>
-svn: Can't recode string.
+svn: Can't convert string from native encoding to 'UTF-8':
+…
+svn: Can't convert string from 'UTF-8' to native encoding:
+…
</screen>
- <para>这个信息是神秘的，但是通常会发生在Subversion客户端从版本库接收到一个UTF-8串，但是字符不能转化为当前的地区文字，举个例子，如果你的地区设置是<literal>en_US</literal>，但是一个写作者使用日本文件名提交，你会在<command>svn
+ <para>这个错误信息通常会发生在Subversion客户端从版本库接收到一个UTF-8串，但字符不能转化为当前的地区文字时，举个例子，如果你的地区设置是<literal>en_US</literal>，但是一个写作者使用日本文件名提交，你会在<command>svn
update</command>接受文件时会看到这个错误。</para>
<para>解决方案或者是设置你的地区为<emphasis>可以</emphasis>表示即将到来的UTF-8数据，或者是修改版本库的文件名或信息。（不要忘记和你的合作者拍拍手—项目必须首先决定通用的语言，这样所有的参与者会使用相同的地区设置。）</para>
@@ -1233,10 +1898,249 @@
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 6: SUBVERSION REPOSITORY URLS *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-7-sect-6">
+<!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.externaldifftools">
+ <title>Using External Differencing Tools</title>
+
+ <para>The presence of <option>--diff-cmd</option> and
+ <option>--diff3-cmd</option> options, and similarly named
+ runtime configuration parameters (see <xref
+ linkend="svn.advanced.confarea.opts.config"/>), can lead to a
+ false notion of how easy it is to use external differencing (or
+ <quote>diff</quote>) and merge tools with Subversion. While
+ Subversion can use most of popular such tools available, the
+ effort invested in setting this up often turns out to be
+ non-trivial.</para>
+
+ <para>The interface between Subversion and external diff and merge
+ tools harkens back to a time when Subversion's only contextual
+ differencing capabilities were built around invocations of the
+ GNU diffutils toolchain, specifically the
+ <command>diff</command> and <command>diff3</command> utilities.
+ To get the kind of behavior Subversion needed, it called these
+ utilities with more than a handful of options and parameters,
+ most of which were quite specific to the utilities. Some time
+ later, Subversion grew its own internal differencing library,
+ and as a failover mechanism,
+ <footnote>
+ <para>Subversion developers are good, but even the best make
+ mistakes.</para>
+ </footnote>
+ the <option>--diff-cmd</option> and <option>--diff3-cmd</option>
+ options were added to the Subversion command-line client so
+ users could more easily indicate that they preferred to use the
+ GNU diff and diff3 utilities instead of the newfangled internal
+ diff library. If those options were used, Subversion would
+ simply ignore the internal diff library, and fall back to
+ running those external programs, lengthy argument lists and all.
+ And that's where things remain today.</para>
+
+ <para>It didn't take long for folks to realize that having such
+ easy configuration mechanisms for specifying that Subversion
+ should use the external GNU diff and diff3 utilities located at
+ a particular place on the system could be applied toward the use
+ of other diff and merge tools, too. After all, Subversion
+ didn't actually verify that the things it was being told to run
+ were members of the GNU diffutils toolchain. But the only
+ configurable aspect of using those external tools is their
+ location on the system—not the option set, parameter
+ order, etc. Subversion continues throwing all those GNU utility
+ options at your external diff tool regardless of whether or not
+ that program can understand those options. And that's where
+ things get unintuitive for most users.</para>
+
+ <para>The key to using external diff and merge tools (other than
+ GNU diff and diff3, of course) with Subversion is to use wrapper
+ scripts which convert the input from Subversion into something
+ that your differencing tool can understand, and then to convert
+ the output of your tool back into a format which Subversion
+ expects—the format that the GNU tools would have used.
+ The following sections cover the specifics of those
+ expectations.</para>
+
+ <note>
+ <para>The decision on when to fire off a contextual diff or
+ merge as part of a larger Subversion operation is made
+ entirely by Subversion, and is affected by, among other
+ things, whether or not the files being operated on are
+ human-readable as determined by their
+ <literal>svn:mime-type</literal> property. This means, for
+ example, that even if you had the niftiest Microsoft
+ Word-aware differencing or merging tool in the Universe, it
+ would never be invoked by Subversion so long as your versioned
+ Word documents had a configured MIME type that denoted that
+ they were not human-readable (such as
+ <literal>application/msword</literal>). For more about MIME
+ type settings, see <xref
+ linkend="svn.advanced.props.special.mime-type"/></para>
+ </note>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.externaldifftools.diff">
+ <title>External diff</title>
+
+ <para>Subversion calls external diff programs with parameters
+ suitable for the GNU diff utility, and expects only that the
+ external program return with a successful error code. For
+ most alternative diff program, only the sixth and seventh
+ arguments, the paths of the files which represent the left and
+ right sides of the diff, respectively, are of interest. Note
+ that Subversion runs the diff program once per modified file
+ covered by the Subversion operation, so if your program runs
+ in an asynchronous fashion (or <quote>backgrounded</quote>),
+ you might have several instances of it all running
+ simultaneously. Finally, Subversion expects that your program
+ return an errorcode of 0 if your program detected differences,
+ or 1 if it did not—any other errorcode is considered a
+ fatal error.
+ <footnote>
+ <para>The GNU diff manual page puts it this way: <quote>An
+ exit status of 0 means no differences were found, 1 means some
+ differences were found, and 2 means trouble.</quote></para>
+ </footnote>
+ </para>
+
+ <para><xref linkend="svn.advanced.externaldifftools.diff.ex-1"/>
+ and <xref linkend="svn.advanced.externaldifftools.diff.ex-2"/>
+ are templates for external diff tool wrappers in the Bourne
+ shell and Windows batch scripting languages,
+ respectively.</para>
+
+ <example id="svn.advanced.externaldifftools.diff.ex-1">
+ <title>diffwrap.sh</title>
+ <programlisting>
+#!/bin/sh
+
+# Configure your favorite diff program here.
+DIFF="/usr/local/bin/my-diff-tool"
+
+# Subversion provides the paths we need as the sixth and seventh
+# parameters.
+LEFT=${6}
+RIGHT=${7}
+
+# Call the diff command (change the following line to make sense for
+# your merge program).
+$DIFF --left $LEFT --right $RIGHT
+
+# Return an errorcode of 0 if no differences were detected, 1 if some were.
+# Any other errorcode will be treated as fatal.
+</programlisting>
+ </example>
+
+ <example id="svn.advanced.externaldifftools.diff.ex-2">
+ <title>diffwrap.bat</title>
+ <programlisting>
+ at ECHO OFF
+
+REM Configure your favorite diff program here.
+SET DIFF="C:\Program Files\Funky Stuff\My Diff Tool.exe"
+
+REM Subversion provides the paths we need as the sixth and seventh
+REM parameters.
+SET LEFT=%6
+SET RIGHT=%7
+
+REM Call the diff command (change the following line to make sense for
+REM your merge program).
+%DIFF% --left %LEFT% --right %RIGHT%
+
+REM Return an errorcode of 0 if no differences were detected, 1 if some were.
+REM Any other errorcode will be treated as fatal.
+</programlisting>
+ </example>
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.externaldifftools.diff3">
+ <title>External diff3</title>
+
+ <para>Subversion calls external merge programs with parameters
+ suitable for the GNU diff3 utility, expecting that the
+ external program return with a successful error code and that
+ the full file contents which result from the completed merge
+ operation are printed on the standard output stream (so that
+ Subversion can redirect them into the appropriate version
+ controlled file). For most alternative merge programs, only
+ the ninth, tenth, and eleventh arguments, the paths of the
+ files which represent the <quote>mine</quote>,
+ <quote>older</quote>, and <quote>yours</quote> inputs,
+ respectively, are of interest. Note that because Subversion
+ depends on the output of your merge program, you wrapper
+ script must not exit before that output has been delivered to
+ Subversion. When it finally does exit, it should return an
+ errorcode of 0 if the merge was successful, or 1 if unresolved
+ conflicts remain in the output—any other errorcode is
+ considered a fatal error.</para>
+
+ <para><xref linkend="svn.advanced.externaldifftools.diff3.ex-1"/>
+ and <xref linkend="svn.advanced.externaldifftools.diff3.ex-2"/> are
+ templates for external merge tool wrappers in the Bourne shell
+ and Windows batch scripting languages, respectively.</para>
+
+ <example id="svn.advanced.externaldifftools.diff3.ex-1">
+ <title>diff3wrap.sh</title>
+ <programlisting>
+#!/bin/sh
+
+# Configure your favorite diff3/merge program here.
+DIFF3="/usr/local/bin/my-merge-tool"
+
+# Subversion provides the paths we need as the ninth, tenth, and eleventh
+# parameters.
+MINE=${9}
+OLDER=${10}
+YOURS=${11}
+
+# Call the merge command (change the following line to make sense for
+# your merge program).
+$DIFF3 --older $OLDER --mine $MINE --yours $YOURS
+
+# After performing the merge, this script needs to print the contents
+# of the merged file to stdout. Do that in whatever way you see fit.
+# Return an errorcode of 0 on successful merge, 1 if unresolved conflicts
+# remain in the result. Any other errorcode will be treated as fatal.
+</programlisting>
+ </example>
+
+ <example id="svn.advanced.externaldifftools.diff3.ex-2">
+ <title>diff3wrap.bat</title>
+ <programlisting>
+ at ECHO OFF
+
+REM Configure your favorite diff3/merge program here.
+SET DIFF3="C:\Program Files\Funky Stuff\My Merge Tool.exe"
+
+REM Subversion provides the paths we need as the ninth, tenth, and eleventh
+REM parameters. But we only have access to nine parameters at a time, so we
+REM shift our nine-parameter window twice to let us get to what we need.
+SHIFT
+SHIFT
+SET MINE=%7
+SET OLDER=%8
+SET YOURS=%9
+
+REM Call the merge command (change the following line to make sense for
+REM your merge program).
+%DIFF3% --older %OLDER% --mine %MINE% --yours %YOURS%
+
+REM After performing the merge, this script needs to print the contents
+REM of the merged file to stdout. Do that in whatever way you see fit.
+REM Return an errorcode of 0 on successful merge, 1 if unresolved conflicts
+REM remain in the result. Any other errorcode will be treated as fatal.
+</programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.advanced.reposurls">
<title>Subversion版本库URL</title>
<para>正如我们在整本书里描述的，Subversion使用URL来识别Subversion版本库中的版本化资源，通常情况下，这些URL使用标准的语法，允许服务器名称和端口作为URL的一部分：</para>
Modified: trunk/src/zh/book/ch08.xml
==============================================================================
--- trunk/src/zh/book/ch08.xml (original)
+++ trunk/src/zh/book/ch08.xml Wed Jan 25 01:01:34 2006
@@ -10,16 +10,16 @@
</simplesect>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 1: LAYERED LIBRARY DESIGN *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-8-sect-1">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.developer.layerlib">
<title>分层的库设计</title>
<para>Subversion有一个模块化的设计，通过一套C库<footnote><para>译者：这里的“库（library）”指函数库，与文中大量出现的“版本库（Repository）”不同，一般情况下，作为独词出现的“库”应属于前者。</para>
- </footnote>来实现。每一个库都有一套定义良好的目标与接口，据称，大部分模块都属于三层中的某一层—版本库层、版本库访问（RA）层或是客户端层。我们很快就会考察这些层，但首先让我们看一下<xref linkend="svn-ch-8-table-1"/>中的有关于Subversion库的摘要目录，为了一致性，我们将通过它们的无扩展Unix库名（例如libsvn_fs、libsvn_wc和mod_dav_svn）来引用它们。</para>
+ </footnote>来实现。每一个库都有一套定义良好的目标与接口，据称，大部分模块都属于三层中的某一层—版本库层、版本库访问（RA）层或是客户端层。我们很快就会考察这些层，但首先让我们看一下<xref linkend="svn.developer.layerlib.tbl-1"/>中的有关于Subversion库的摘要目录，为了一致性，我们将通过它们的无扩展Unix库名（例如libsvn_fs、libsvn_wc和mod_dav_svn）来引用它们。</para>
- <table id="svn-ch-8-table-1">
+ <table id="svn.developer.layerlib.tbl-1">
<title>Subversion库的摘要目录</title>
<tgroup cols="2">
<thead>
@@ -38,8 +38,12 @@
<entry>目录树和文本区别程序</entry>
</row>
<row>
+ <entry>libsvn_diff</entry>
+ <entry>Contextual differencing and merging routines</entry>
+ </row>
+ <row>
<entry>libsvn_fs</entry>
- <entry>Subversion文件系统库</entry>
+ <entry>Subversion文件系统库和模块加载器</entry>
</row>
<row>
<entry>libsvn_fs_base</entry>
@@ -89,22 +93,22 @@
</tgroup>
</table>
- <para>单词<quote>各色各样的</quote>只在列表<xref linkend="svn-ch-8-table-1"/>中出现过一次是一个好的迹象。Subversion开发团队非常注意将功能归入合适的层和库，或许模块化设计最大的好处就是从开发者的角度看减少了复杂性。作为一个开发者，你可以很快就描画出一副<quote>大图像</quote>，以便于你更精确地，也相对容易地找出某一功能所在的位置。</para>
+ <para>单词<quote>各色各样的</quote>只在列表<xref linkend="svn.developer.layerlib.tbl-1"/>中出现过一次是一个好的迹象。Subversion开发团队非常注意将功能归入合适的层和库，或许模块化设计最大的好处就是从开发者的角度看减少了复杂性。作为一个开发者，你可以很快就描画出一副<quote>大图像</quote>，以便于你更精确地，也相对容易地找出某一功能所在的位置。</para>
- <para>模块化的另一个好处是我们有能力去构造一个全新的，能够完全实现相同API功能的库，以替换整个给定的模块，而又不会影响基础代码。在某种意义上，Subversion已经这样做了。libsvn_ra_dav、libsvn_ra_local和libsvn_ra_svn all都实现了相同的接口，三者均与版本库层进行通讯—libsvn_ra_dav和libsvn_ra_svn通过网络，而libsvn_ra_local则是直接连接。
+ <para>模块化的另一个好处是我们有能力去构造一个全新的，能够完全实现相同API功能的库，以替换整个给定的模块，而又不会影响基础代码。在某种意义上，Subversion已经这样做了。libsvn_ra_dav、libsvn_ra_local和libsvn_ra_svn all都实现了相同的接口，三者均与版本库层进行通讯—libsvn_ra_dav和libsvn_ra_svn通过网络，而libsvn_ra_local则是直接连接，libsvn_fs_base和libsvn_fs_fs是另外两个例子。
</para>
<para>客户端设计本身就给模块化设计理念增色不少，Subversion目前只是附带了一个命令行方式的客户端，但已经出现了一些由第三方开发的GUI客户端程序，这些GUI客户端程序全都使用了与原装命令行客户端程序相同的API。为了开发一个实用的Subversion客户端程序，对于绝大部分功能，仅使用Subversion的libsvn_client库就够了（见<xref
- linkend="svn-ch-8-sect-1.3"/>）。</para>
+ linkend="svn.developer.layerlib.client"/>）。</para>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-1.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.layerlib.repos">
<title>版本库层</title>
<para>当提到Subversion版本库层时，我们通常会讨论两个库—版本库（函数）库和文件系统（函数）库。这两个库为你的版本控制数据的各个修订版本提供了存储和报告机制，该层通过版本库访问层连接到客户层，而且，从Subversion用户的角度看，这是资料存储过程中的<quote>链接的另一端</quote>。</para>
<para>Subversion文件系统通过libsvn_fs API来访问，它并不是一个安装在操作系统之上的内核级的文件系统（例如Linux ext2或NTFS），而是一个虚拟文件系统。它并未将<quote>文件</quote>和<quote>目录</quote>保存为真实的文件和目录（也就是用你熟知的shell程序可以浏览的那种），而是采用了一种抽象的后端存储方式，这个后端存储方式有两种—一个是Berkeley DB数据库环境，另一个是普通文件表示。（要了解更多关于版本库后端的信息，请看<xref
- linkend="svn-ch-5-sect-1.3"/>）。除此之外，开发社区也非常有兴趣考虑在Subversion的未来版本 中提供某种使用其它后端数据库系统的能力，也许是开放式数据库连接（ODBC）的机制。</para>
+ linkend="svn.reposadmin.basics.backends"/>）。除此之外，开发社区也非常有兴趣考虑在Subversion的未来版本 中提供某种使用其它后端数据库系统的能力，也许是开放式数据库连接（ODBC）的机制。</para>
<para>libsvn_fs支持的文件系统API包含了所有其他文件系统的功能：你可以创建和删除文件和目录、拷贝和移动、修改文件内容等等。它也包含了一些不太常用的特性，如对任意文件和目录添加、修改和删除元数据（<quote>properties</quote>）的能力。此外，Subversion文件系统是一个版本化的文件系统，意味着你修改你的目录树时，Subversion会记住修改以前的样子。等等，可以回到所有初始化版本库之后（且仅仅之后）的版本。</para>
@@ -142,10 +146,10 @@
<para>大多数文件系统接口提供的功能作为一个动作发生在一个文件系统路径上，也就是，从文件系统的外部，描述和访问文件和目录独立版本的主要机制是经过如<filename>/foo/bar</filename>的路径，就像你在喜欢的shell程序中定位文件和目录。你通过传递它们的路径到相应的API功能来添加新的文件和目录，查询这些信息也是同样的机制。
</para>
- <para>不像大多数文件系统，尽管，一个单独的路径不足以在Subversion定位一个文件或目录，可以把目录树看作一个二维的系统，一个节点的兄弟代表了一种从左到右的动作，并且递减到子目录是一个向下的动作，<xref linkend="svn-ch-8-dia-1"/>展示了一个典型的树的形式。
+ <para>不像大多数文件系统，尽管，一个单独的路径不足以在Subversion定位一个文件或目录，可以把目录树看作一个二维的系统，一个节点的兄弟代表了一种从左到右的动作，并且递减到子目录是一个向下的动作，<xref linkend="svn.developer.layerlib.repos.dia-1"/>展示了一个典型的树的形式。
</para>
- <figure id="svn-ch-8-dia-1">
+ <figure id="svn.developer.layerlib.repos.dia-1">
<title>二维的文件目录</title>
<graphic fileref="images/ch08dia1.png"/>
</figure>
@@ -156,10 +160,10 @@
</para>
</footnote>
在一个文件系统接口，几乎所有的功能都有个<parameter>路径</parameter>参数，也期望一个<parameter>root</parameter>参数。<structname>svn_fs_root_t</structname>参数不仅描述了一个修订版本或一个Subversion事务（通常正好是一个修订版本），而且提供了用来区分修订版本32的<filename>/foo/bar</filename>和修订版本98在同样路径的三维上下文环境。<xref
- linkend="svn-ch-8-dia-2"/>展示了修订版本历史作为添加的纬度进入到Subversion文件系统领域。
+ linkend="svn.developer.layerlib.repos.dia-2"/>展示了修订版本历史作为添加的纬度进入到Subversion文件系统领域。
</para>
- <figure id="svn-ch-8-dia-2">
+ <figure id="svn.developer.layerlib.repos.dia-2">
<title>版本时间—第三维！</title>
<graphic fileref="images/ch08dia2.png"/>
</figure>
@@ -178,10 +182,10 @@
<para>希望使用libsvn_repos的API的开发者会发现它不是文件系统的一个完全包裹，只有文件系统常规周期中的主要事件使用版本库接口包裹，如包括Subversion事务的创建和提交，修订版本属性的修改。这些特别的事件使用版本库库包裹是因为它们有一些关联的钩子，在将来，别的事件也将会使用版本库API包裹。所有其它的文件系统交互会直接通过libsvn_fs的API发生。
</para>
- <para>举个例子，这里是使用版本库和文件系统接口创建文件系统新修订版本的代码块，新版本包括添加一个新目录。注意这个例子（和其它本书中的代码），这个<function>SVN_ERR</function>宏只是简单的检查是否有一个非成功的错误从包裹的函数中返回，如果存在就会返回错误。
+ <para>举个例子，这里是使用版本库和文件系统接口创建文件系统新修订版本的代码块，新版本包括添加一个新目录。注意这个例子（和其它本书中的代码），这个<function>SVN_ERR()</function>宏只是简单的检查是否有一个非成功的错误从包裹的函数中返回，如果存在就会返回错误。
</para>
- <example id="svn-ch-8-sect-1.1-ex-1">
+ <example id="svn.developer.layerlib.repos.ex-1">
<title>使用版本库层</title>
<programlisting>
@@ -237,7 +241,7 @@
printf ("Directory '%s' was successfully added as new revision "
"'%ld'.\n", new_directory, youngest_rev);
}
- else if (err->apr_err == SVN_ERR_FS_CONFLICT)
+ else if ((err->apr_err == SVN_ERR_FS_CONFLICT)
{
/* Uh-oh. Our commit failed as the result of a conflict
(someone else seems to have made changes to the same area
@@ -261,8 +265,8 @@
</programlisting>
</example>
- <para>在前面的代码片断中，同时调用了版本库和文件系统接口，我们可以正像这样简单的用<function>svn_fs_commit_txn</function>提交事务。但是文件系统的API对版本库库的钩子一无所知，如果你希望你的Subversion版本库在每次提交一个事务时自动执行一些非Subversion的任务（例如，给开发者邮件组发送一个描述事务修改的邮件），你需要使用libsvn_repos包裹的功能版本—<function>svn_repos_fs_commit_txn</function>。这个功能会实际上首先运行一个如果存在的<literal>pre-commit</literal>钩子脚本，然后提交事务，最后会运行一个<literal>post-commit</literal>钩子脚本。钩子提供了一种特别的报告机制，不是真的属于核心文件系统库本身。（关于Subversion版本库钩子的更多信息，见<xref
- linkend="svn-ch-5-sect-2.1" />。）</para>
+ <para>在前面的代码片断中，同时调用了版本库和文件系统接口，我们可以正像这样简单的用<function>svn_fs_commit_txn()</function>提交事务。但是文件系统的API对版本库库的钩子一无所知，如果你希望你的Subversion版本库在每次提交一个事务时自动执行一些非Subversion的任务（例如，给开发者邮件组发送一个描述事务修改的邮件），你需要使用libsvn_repos包裹的功能版本—<function>svn_repos_fs_commit_txn()</function>。这个功能会实际上首先运行一个如果存在的<literal>pre-commit</literal>钩子脚本，然后提交事务，最后会运行一个<literal>post-commit</literal>钩子脚本。钩子提供了一种特别的报告机制，不是真的属于核心文件系统库本身。（关于Subversion版本库钩子的更多信息，见<xref
+ linkend="svn.reposadmin.create.hooks" />。）</para>
<para>钩子机制需求是从文件系统代码的其它部分中抽象出单独的版本库库的一个原因，libsvn_repos的API提供了许多其他有用的工具，它们可以做到：
</para>
@@ -292,8 +296,8 @@
</sect2>
- <!-- ****************************************************************** -->
- <sect2 id="svn-ch-8-sect-1.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.layerlib.ra">
<title>版本库访问层</title>
<para>如果说Subversion版本库层是在<quote>这条线的另一端</quote>，那版本库访问层就是这条线。负责在客户端库和版本库之间编码数据，这一层包括libsvn_ra模块加载模块，RA模块本身（现在包括了libsvn_ra_dav、libsvn_ra_local和libsvn_ra_svn），和所有一个或多个RA模块需要的附加库，例如与Apache模块mod_dav_svn通讯的libsvn_ra_dav或者是libsvn_ra_svn的服务器，<command>svnserve</command>。
@@ -303,25 +307,26 @@
<screen>
$ svn --version
-svn, version 1.0.1 (r9023)
- compiled Mar 17 2004, 09:31:13
+svn, version 1.2.3 (r15833)
+ compiled Sep 13 2005, 22:45:22
-Copyright (C) 2000-2004 CollabNet.
+Copyright (C) 2000-2005 CollabNet.
Subversion is open source software, see http://subversion.tigris.org/
This product includes software developed by CollabNet (http://www.Collab.Net/).
The following repository access (RA) modules are available:
* ra_dav : Module for accessing a repository via WebDAV (DeltaV) protocol.
- - handles 'http' schema
- - handles 'https' schema
-* ra_local : Module for accessing a repository on local disk.
- - handles 'file' schema
+ - handles 'http' scheme
+ - handles 'https' scheme
* ra_svn : Module for accessing a repository using the svn network protocol.
- - handles 'svn' schema
+ - handles 'svn' scheme
+* ra_local : Module for accessing a repository on local disk.
+ - handles 'file' scheme
+
</screen>
- <sect3 id="svn-ch-8-sect-1.2.1">
+ <sect3 id="svn.developer.layerlib.ra.dav">
<title>RA-DAV（使用HTTP/DAV版本库访问）</title>
<para>libsvn_ra_dav库是给在不同机器使用<literal>http:</literal>或<literal>https:</literal>协议访问服务器的用户设计的，为了理解这个模块的工作，我们首先要知道这种版本库访问层中的特定配置的关键组成部分—强大的Apache HTTP服务器，和Neon HTTP/WebDAV客户端库。</para>
@@ -330,7 +335,7 @@
<para>Subversion使用HTTP和WebDAV（和DeltaV）来与Apache服务器通讯，你可以在本章的WebDAV读到更多信息，但简而言之，WebDAV和DeltaV是标准HTTP 1.1协议的扩展，允许在web上对文件进行分享和版本操作。Apache 2.0版随着一个mod_dav，一个Apache理解HTTP DAV扩展的模块，Subversion本身提供了mod_dav_svn，尽管，这是另一个Apache模块，它与mod_dav结合（实际上mod_dav_svn是作为后端支持）使用来提供Subversion对WebDAV和DeltaV的实现。</para>
- <para>当与版本库通过HTTP通讯时，RA加载器库选择libsvn_ra_dav作为正确的访问模块，Subversion客户端调用原始的RA接口，libsvn_ra_dav把这些调用（包含了大量Subversion操作）影射为一系列HTTP/WebDAV请求。使用Neon库，libsvn_ra_dav把这些请求传递到Apache服务器，Apache接受到这些请求（就像平时web服务器常做的那样处理原始的HTTP请求），注意到这些请求的URL已经配置为DAV的位置（使用<filename>httpd.conf</filename>的<sgmltag>Location</sgmltag>指示），并且会使用自己的mod_dav模块来处理。当正确的配置了mod_dav使之知道了使用mod_dav_svn来处理所有文件系统相关的要求，而不是使用默认的Apache自带的原始mod_dav_fs来处理。所以最终客户端是与mod_dav_svn通讯，直接与Subversion版本库层绑定。</para>
+ <para>当与版本库通过HTTP通讯时，RA加载器库选择libsvn_ra_dav作为正确的访问模块，Subversion客户端调用原始的RA接口，libsvn_ra_dav把这些调用（包含了大量Subversion操作）影射为一系列HTTP/WebDAV请求。使用Neon库，libsvn_ra_dav把这些请求传递到Apache服务器，Apache接受到这些请求（就像平时web服务器常做的那样处理原始的HTTP请求），注意到这些请求的URL已经配置为DAV的位置（使用<filename>httpd.conf</filename>的<literal><Location></literal>指示），并且会使用自己的mod_dav模块来处理。当正确的配置了mod_dav使之知道了使用mod_dav_svn来处理所有文件系统相关的要求，而不是使用默认的Apache自带的原始mod_dav_fs来处理。所以最终客户端是与mod_dav_svn通讯，直接与Subversion版本库层绑定。</para>
<para>有一个实际交换发生的简单描述，举个例子，Subversion版本库可以使用Apache的授权指示进行保护。这会导致初始的与版本库的通讯会被Apache的授权基础拒绝，在此刻，libsvn_ra_dav将提供不足鉴定的通知返回，并且回调客户端层来得到一些更新的认证数据。如果数据是正确提供，而且用户有访问的权限，会赋予libsvn_ra_dav的下一个对原操作的自动尝试权限，并且一切会很好。如果足够的认证信息不能提供，请求会最后失败，客户端也会报告给用户失败信息。</para>
@@ -349,7 +354,7 @@
</sect3>
- <sect3 id="svn-ch-8-sect-1.2.2">
+ <sect3 id="svn.developer.layerlib.ra.svn">
<title>RA-SVN（自定义协议版本库访问）</title>
<para>作为标准HTTP/WebDAV协议的补充，Subversion也提供了一个使用自定义协议的RA实现，libsvn_ra_svn模块实现了自己的网络套接字连接，与一个独立服务器通讯—<filename>svnserve</filename>程序—在存放版本库的机器上。客户端可以使用<literal>svn://</literal>访问版本库。
@@ -360,7 +365,7 @@
</sect3>
- <sect3 id="svn-ch-8-sect-1.2.3">
+ <sect3 id="svn.developer.layerlib.ra.local">
<title>RA-Local（直接版本库访问）</title>
<para>并不是所有与Subversion版本库的通讯需要服务器进程和一个网络层。用户如果只是希望简单的访问本地磁盘的版本库，他们会使用<literal>file:</literal>的URL和libsvn_ra_local提供的功能。RA模块直接与版本库和文件系统库绑定，所以不需要网络通讯。
@@ -370,12 +375,12 @@
</para>
<para>也必须意识到Subversion的<literal>file:</literal> URL不能和在普通的web服务器中的<literal>file:</literal> URL一样工作。当你尝试在web服务器查看一个<literal>file:</literal>的URL，它会通过直接检测文件系统读取和显示那个位置的文件内容，但是Subversion的资源存在于虚拟文件系统（见<xref
- linkend="svn-ch-8-sect-1.1" />）中，你的浏览器不会理解怎样读取这个文件系统。
+ linkend="svn.developer.layerlib.repos" />）中，你的浏览器不会理解怎样读取这个文件系统。
</para>
</sect3>
- <sect3 id="svn-ch-8-sect-1.2.4">
+ <sect3 id="svn.developer.layerlib.ra.yours">
<title>你的RA库在这里</title>
<para>对那些一直希望使用另一个协议来访问Subversion版本库的人，正好是为什么版本库访问层是模块化的！开发者可以简单的编写一个新的库来在一侧实现RA接口并且与另一侧的版本库通讯。你的新库可以使用存在的网络协议，或者发明你自己的。你可以使用进程间的通讯调用，或者—让我们发狂，我们会吗？—你甚至可以实现一个电子邮件为基础的协议，Subversion提供了API，你提供创造性。
@@ -384,18 +389,18 @@
</sect3>
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-1.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.layerlib.client">
<title>客户端层</title>
<para>在客户端这一面，Subversion工作拷贝是所有动作发生的地方。大多数客户端库实现的功能是为了管理工作拷贝的目的实现的—满是文件子目录的目录是一个或多个版本库位置的可编辑的本地<quote>影射</quote>—从版本库访问层来回传递修改。
</para>
<para>Subversion的工作拷贝库，libsvn_wc直接负责管理工作拷贝的数据，为了完成这一点，库会在工作拷贝的每个目录的特殊子目录中保存关于工作拷贝的管理性信息。这个子目录叫做<filename>.svn</filename>，出现在所有工作拷贝目录里，保存了各种记录了状态和用来在私有工作区工作的文件和目录。对那些熟悉CVS的用户，<filename>.svn</filename>子目录与<filename>CVS</filename>工作拷贝管理目录的作用类似，关于<filename>.svn</filename>管理区域的更多信息，见本章的<xref
- linkend="svn-ch-8-sect-3"/>。
+ linkend="svn.developer.insidewc"/>。
</para>
- <para>Subversion客户端库libsvn_client具备最广泛的职责；它的工作是结合工作拷贝库和版本库访问库的功能，然后为希望普通版本控制的应用提供最高级的API。举个例子，<function>svn_client_checkout</function>方法是用一个URL作为参数，传递这个URL到RA层然后在特定版本库打开一个会话。然后向版本库要求一个特定的目录树，然后把目录树发送给工作拷贝库，然后把完全的工作拷贝写到磁盘（<filename>.svn</filename>目录和一切）。</para>
+ <para>Subversion客户端库libsvn_client具备最广泛的职责；它的工作是结合工作拷贝库和版本库访问库的功能，然后为希望普通版本控制的应用提供最高级的API。举个例子，<function>svn_client_checkout()</function>方法是用一个URL作为参数，传递这个URL到RA层然后在特定版本库打开一个会话。然后向版本库要求一个特定的目录树，然后把目录树发送给工作拷贝库，然后把完全的工作拷贝写到磁盘（<filename>.svn</filename>目录和一切）。</para>
<para>客户端库是为任何程序使用设计的，尽管Subversion的源代码包括了一个标准的命令行客户端，用客户端库编写GUI客户端也是很简单，Subversion新的GUI（或者任何新的客户端，真的）不需要紧密围绕包含的命令行客户端—他们对具有相同功能、数据和回调机制的libsvn_client的API有完全的访问权利。
</para>
@@ -414,10 +419,10 @@
</sect2>
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 2: USING THE APIS *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-8-sect-2">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.developer.usingapi">
<title>使用API</title>
<para>使用Subversion库API开发应用看起来相当的直接，所有的公共头文件放在源文件的<filename>subversion/include</filename>目录，从源代码编译和安装Subversion本身，需要这些头文件拷贝到系统位置。这些头文件包括了所有用户可以访问的功能和类型。
@@ -426,10 +431,10 @@
<para>你首先应该注意Subversion的数据类型和方法是命名空间保护的，每一个公共Subversion对象名以<literal>svn_</literal>开头，然后紧跟一个这个对象定义（如<literal>wc</literal>、<literal>client</literal>和<literal>fs</literal>其他）所在的库的简短编码，然后是一个下划线（<literal>_</literal>）和后面的对象名称。半公开的方法（库使用，但是但库之外代码不可以使用并且只可以在库自己的目录看到）与这个命名模式不同，并不是库代码之后紧跟一个下划线，他们是用两个下划线（<literal>__</literal>）。给定源文件的私有方法没有特殊前缀，使用<literal>static</literal>声明。当然，一个编译器不会关心命名习惯，只是用来区分给定方法或数据类型。
</para>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-2.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.usingapi.apr">
<title>Apache可移植运行库</title>
- <para>伴随Subversion自己的数据类型，你会看到许多<literal>apr_</literal>开头的数据类型引用—来自Apache可移植运行库（APR）的对象。APR是Apache可移植运行库，源自为了服务器代码的多平台性，尝试将不同的操作系统特定字节与操作系统无关代码隔离。结果就提供了一个基础API的库，只有一些适度区别—或者是广泛的—来自各个操作系统。Apache HTTP服务器很明显是APR库的第一个用户，Subversion开发者立刻发现了使用APR库的价值。意味着Subversion没有操作系统特定的代码，也意味着Subversion客户端可以在Server存在的平台编译和运行。当前这个列表包括，各种类型的Unix、Win32、OS/2和Mac OS X。
+ <para>伴随Subversion自己的数据类型，你会看到许多<literal>apr</literal>开头的数据类型引用—来自Apache可移植运行库（APR）的对象。APR是Apache可移植运行库，源自为了服务器代码的多平台性，尝试将不同的操作系统特定字节与操作系统无关代码隔离。结果就提供了一个基础API的库，只有一些适度区别—或者是广泛的—来自各个操作系统。Apache HTTP服务器很明显是APR库的第一个用户，Subversion开发者立刻发现了使用APR库的价值。意味着Subversion没有操作系统特定的代码，也意味着Subversion客户端可以在Server存在的平台编译和运行。当前这个列表包括，各种类型的Unix、Win32、OS/2和Mac OS X。
</para>
<para>除了提供了跨平台一致的系统调用，
@@ -437,122 +442,255 @@
<para>Subversion使用尽可能多ANSI系统调用和数据类型。
</para>
</footnote>
- APR给Subversion对多种数据类型有快速的访问，如动态数组和哈希表。Subversion在代码中广泛使用这些类型，但是或许大多数普遍深入的APR数据类型可以在所有的Subversion的API原型中发现，是<literal>apr_pool_t</literal>—APR内存池，Subversion使用内部缓冲池用来进行内存分配（除非外部库在API传递参数时需要一个不同的内存管理模式），
+ APR给Subversion对多种数据类型有快速的访问，如动态数组和哈希表。Subversion在代码中广泛使用这些类型，但是或许大多数普遍深入的APR数据类型可以在所有的Subversion的API原型中发现，是<structname>apr_pool_t</structname>—APR内存池，Subversion使用内部缓冲池用来进行内存分配（除非外部库在API传递参数时需要一个不同的内存管理模式），
<footnote>
<para>Neon和Berkeley DB就是这种库的例子。</para>
</footnote>
- 而且一个人如果针对Subversion的API编码不需要做同样的事情，他们可以在需要时给API提供缓冲池，这意味着Subversion的API使用者也必须链接到APR，必须调用<function>apr_initialize()</function>来初始化APR字系统，然后必须得到一个缓冲池用来进行Subversion的API调用。详情见<xref linkend="svn-ch-8-sect-5"/>。
+ 而且一个人如果针对Subversion的API编码不需要做同样的事情，他们可以在需要时给API提供缓冲池，这意味着Subversion的API使用者也必须链接到APR，必须调用<function>apr_initialize()</function>来初始化APR字系统，然后必须得到一个缓冲池用来进行Subversion的API调用。详情见<xref linkend="svn.developer.pools"/>。
</para>
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-2.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.usingapi.urlpath">
<title>URL和路径需求</title>
<para>因为分布式版本控制操作是Subversion存在的重点，有意义来关注一下国际化（i18n）支持。毕竟，当<quote>分布式</quote>或许意味着<quote>横跨办公室</quote>，它也意味着<quote>横跨全球</quote>。为了更容易一点，Subversion的所有公共接口只接受路径参数,这些参数是传统的，使用UTF-8编码。这意味着，举个例子，任何新的使用libsvn_client接口客户端库，在把这些参数传递给Subversion库前，需要首先将路径从本地代码转化为UTF-8代码，然后将Subversion传递回来的路径转换为本地代码，很幸运，Subversion提供了一组任何程序可以使用的转化方法（见<filename>subversion/include/svn_utf.h</filename>）。</para>
<para>同样，Subversion的API需要所有的URL参数是正确的URI编码，所以，我们不会传递<systemitem
class="url">file:///home/username/My File.txt</systemitem>作为<literal>My File.txt</literal>的URL，而会传递<systemitem
- class="url">file:///home/username/My%20File.txt</systemitem>。再次，Subversion提供了一些你可以使用的助手方法—<function>svn_path_uri_encode</function>和<function>svn_path_uri_decode</function>，分别用来URI的编码和解码。
+ class="url">file:///home/username/My%20File.txt</systemitem>。再次，Subversion提供了一些你可以使用的助手方法—<function>svn_path_uri_encode()</function>和<function>svn_path_uri_decode()</function>，分别用来URI的编码和解码。
</para>
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-2.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.usingapi.otherlangs">
<title>使用C和C++以外的语言</title>
<para>除C语言以外，如果你对使用其他语言结合Subversion库感兴趣—如Python脚本或是Java应用—Subversion通过简单包裹生成器（SWIG）提供了最初的支持。Subversion的SWIG绑定位于<filename>subversion/bindings/swig</filename>，并且慢慢的走向成熟进入可用状态。这个绑定允许你直接调用Subversion的API方法，使用包裹器会把脚本数据类型转化为Subversion需要的C语言库类型。</para>
<para>通过语言绑定访问Subversion的API有一个明显的好处—简单性。通常来讲，Python和Perl之类的语言比C和C++更加的灵活和简单，这些语言的高级数据类型和上下文驱动类型更加易于处理用户提供的信息，就像你知道的，人们精于把程序搞坏，脚本语言可以更优雅的处理这些错误信息，当然，灵活性经常带来性能的损失，这就是为什么使用紧密优化的，C基础的接口和库组件，然后与一种高效的、灵活的绑定语言，是这样的吸引人。</para>
- <para>让我们看看Subversion的Python SWIG绑定的实例，这个例子和前面的例子作同样的事，注意比较方法的长度和复杂性！</para>
- <example id="svn-ch-8-sect-2.3-ex-1">
+ <para>让我们看看Subversion的Python SWIG绑定的实例，这个例子迭代遍历最新的修订版本，并且打印遍历到的路径。</para>
+
+ <example id="svn.developer.usingapi.otherlangs.ex-1">
<title>使用Python处理版本库层</title>
<programlisting>
-from svn import fs
+#!/usr/bin/python
+
+"""Crawl a repository, printing versioned object path names."""
+
+import sys
import os.path
+import svn.fs, svn.core, svn.repos
+
+def crawl_filesystem_dir(root, directory, pool):
+ """Recursively crawl DIRECTORY under ROOT in the filesystem, and return
+ a list of all the paths at or below DIRECTORY. Use POOL for all
+ allocations."""
+
+ # Print the name of this path.
+ print directory + "/"
+
+ # Get the directory entries for DIRECTORY.
+ entries = svn.fs.svn_fs_dir_entries(root, directory, pool)
+
+ # Use an iteration subpool.
+ subpool = svn.core.svn_pool_create(pool)
+
+ # Loop over the entries.
+ names = entries.keys()
+ for name in names:
+ # Clear the iteration subpool.
+ svn.core.svn_pool_clear(subpool)
+
+ # Calculate the entry's full path.
+ full_path = directory + '/' + name
+
+ # If the entry is a directory, recurse. The recursion will return
+ # a list with the entry and all its children, which we will add to
+ # our running list of paths.
+ if svn.fs.svn_fs_is_dir(root, full_path, subpool):
+ crawl_filesystem_dir(root, full_path, subpool)
+ else:
+ # Else it's a file, so print its path here.
+ print full_path
+
+ # Destroy the iteration subpool.
+ svn.core.svn_pool_destroy(subpool)
+
+def crawl_youngest(pool, repos_path):
+ """Open the repository at REPOS_PATH, and recursively crawl its
+ youngest revision."""
+
+ # Open the repository at REPOS_PATH, and get a reference to its
+ # versioning filesystem.
+ repos_obj = svn.repos.svn_repos_open(repos_path, pool)
+ fs_obj = svn.repos.svn_repos_fs(repos_obj)
+
+ # Query the current youngest revision.
+ youngest_rev = svn.fs.svn_fs_youngest_rev(fs_obj, pool)
+
+ # Open a root object representing the youngest (HEAD) revision.
+ root_obj = svn.fs.svn_fs_revision_root(fs_obj, youngest_rev, pool)
-def crawl_filesystem_dir (root, directory, pool):
- """Recursively crawl DIRECTORY under ROOT in the filesystem, and return
- a list of all the paths at or below DIRECTORY. Use POOL for all
- allocations."""
-
- # Get the directory entries for DIRECTORY.
- entries = fs.dir_entries(root, directory, pool)
-
- # Initialize our returned list with the directory path itself.
- paths = [directory]
-
- # Loop over the entries
- names = entries.keys()
- for name in names:
- # Calculate the entry's full path.
- full_path = os.path.join(basepath, name)
-
- # If the entry is a directory, recurse. The recursion will return
- # a list with the entry and all its children, which we will add to
- # our running list of paths.
- if fs.is_dir(fsroot, full_path, pool):
- subpaths = crawl_filesystem_dir(root, full_path, pool)
- paths.extend(subpaths)
-
- # Else, it is a file, so add the entry's full path to the FILES list.
- else:
- paths.append(full_path)
+ # Do the recursive crawl.
+ crawl_filesystem_dir(root_obj, "", pool)
+
+if __name__ == "__main__":
+ # Check for sane usage.
+ if len(sys.argv) != 2:
+ sys.stderr.write("Usage: %s REPOS_PATH\n"
+ % (os.path.basename(sys.argv[0])))
+ sys.exit(1)
+
+ # Call the app-wrapper, which takes care of APR initialization/shutdown
+ # and the creation and cleanup of our top-level memory pool.
+ svn.core.run_app(crawl_youngest, os.path.normpath(sys.argv[1]))
- return paths
</programlisting>
</example>
- <para>前面C语言的实现确实有一点长，另外C语言的例行公事就是必须关注内存使用，并且需要使用自定义的数据类型来表示条目的哈希值和路径列表。Python有哈希（叫做<quote>dictionaries</quote>）并且列表示内置数据类型，并提供了许多操作这些类型的好方法。而且因为Python使用引用计数来进行垃圾收集，这种语言的用户不需要麻烦自己去分配和回收内存。</para>
+ <para>This same program in C would need to deal with custom
+ datatypes (such as those provided by the APR library) for
+ representing the hash of entries and the list of paths, but
+ Python has hashes (called <quote>dictionaries</quote>) and
+ lists as built-in datatypes, and provides a rich collection of
+ functions for operating on those types. So SWIG (with the
+ help of some customizations in Subversion's language bindings
+ layer) takes care of mapping those custom datatypes into the
+ native datatypes of the target language. This provides a more
+ intuitive interface for users of that language.</para>
+
+ <para>The Subversion Python bindings can be used for working
+ copy operations, too. In the previous section of this
+ chapter, we mentioned the <filename>libsvn_client</filename>
+ interface, and how it exists for the sole purpose of
+ simplifying the process of writing a Subversion client. The
+ following is a brief example of how that library can be
+ accessed via the SWIG bindings to recreate a scaled-down
+ version of the <command>svn status</command> command.</para>
- <para>在本章的前面小节，我们提到<filename>libsvn_client</filename>接口，并且解释了它存在的唯一目的是为了简化编写Subversion客户端的过程，下面是一个如何同SWIG绑定访问库的简短例子，简单的几句Python代码，我们就可以检出一个完全功能的Subversion工作拷贝！</para>
- <example id="svn-ch-8-sect-2.3-ex-2">
- <title>一段检出工作拷贝的简单脚本</title>
+<example id="svn.developer.usingapi.otherlangs.ex-2">
+ <title>A Python Status Crawler</title>
<programlisting>
#!/usr/bin/env python
-import sys
-from svn import util, _util, _client
-def usage():
- print "Usage: " + sys.argv[0] + " URL PATH\n"
- sys.exit(0)
-
-def run(url, path):
- # Initialize APR and get a POOL.
- _util.apr_initialize()
- pool = util.svn_pool_create(None)
-
- # Checkout the HEAD of URL into PATH (silently)
- _client.svn_client_checkout(None, None, url, path, -1, 1, None, pool)
-
- # Cleanup our POOL, and shut down APR.
- util.svn_pool_destroy(pool)
- _util.apr_terminate()
+"""Crawl a working copy directory, printing status information."""
+
+import sys
+import os.path
+import getopt
+import svn.core, svn.client, svn.wc
+def generate_status_code(status):
+ """Translate a status value into a single-character status code,
+ using the same logic as the Subversion command-line client."""
+
+ if status == svn.wc.svn_wc_status_none:
+ return ' '
+ if status == svn.wc.svn_wc_status_normal:
+ return ' '
+ if status == svn.wc.svn_wc_status_added:
+ return 'A'
+ if status == svn.wc.svn_wc_status_missing:
+ return '!'
+ if status == svn.wc.svn_wc_status_incomplete:
+ return '!'
+ if status == svn.wc.svn_wc_status_deleted:
+ return 'D'
+ if status == svn.wc.svn_wc_status_replaced:
+ return 'R'
+ if status == svn.wc.svn_wc_status_modified:
+ return 'M'
+ if status == svn.wc.svn_wc_status_merged:
+ return 'G'
+ if status == svn.wc.svn_wc_status_conflicted:
+ return 'C'
+ if status == svn.wc.svn_wc_status_obstructed:
+ return '~'
+ if status == svn.wc.svn_wc_status_ignored:
+ return 'I'
+ if status == svn.wc.svn_wc_status_external:
+ return 'X'
+ if status == svn.wc.svn_wc_status_unversioned:
+ return '?'
+ return '?'
+
+def do_status(pool, wc_path, verbose):
+ # Calculate the length of the input working copy path.
+ wc_path_len = len(wc_path)
+
+ # Build a client context baton.
+ ctx = svn.client.svn_client_ctx_t()
+
+ def _status_callback(path, status, root_path_len=wc_path_len):
+ """A callback function for svn_client_status."""
+
+ # Print the path, minus the bit that overlaps with the root of
+ # the status crawl
+ text_status = generate_status_code(status.text_status)
+ prop_status = generate_status_code(status.prop_status)
+ print '%s%s %s' % (text_status, prop_status, path[wc_path_len + 1:])
+
+ # Do the status crawl, using _status_callback() as our callback function.
+ svn.client.svn_client_status(wc_path, None, _status_callback,
+ 1, verbose, 0, 0, ctx, pool)
+
+def usage_and_exit(errorcode):
+ """Print usage message, and exit with ERRORCODE."""
+ stream = errorcode and sys.stderr or sys.stdout
+ stream.write("""Usage: %s OPTIONS WC-PATH
+Options:
+ --help, -h : Show this usage message
+ --verbose, -v : Show all statuses, even uninteresting ones
+""" % (os.path.basename(sys.argv[0])))
+ sys.exit(errorcode)
+
if __name__ == '__main__':
- if len(sys.argv) != 3:
- usage()
- run(sys.argv[1], sys.argv[2])
+ # Parse command-line options.
+ try:
+ opts, args = getopt.getopt(sys.argv[1:], "hv", ["help", "verbose"])
+ except getopt.GetoptError:
+ usage_and_exit(1)
+ verbose = 0
+ for opt, arg in opts:
+ if opt in ("-h", "--help"):
+ usage_and_exit(0)
+ if opt in ("-v", "--verbose"):
+ verbose = 1
+ if len(args) != 1:
+ usage_and_exit(2)
+
+ # Call the app-wrapper, which takes care of APR initialization/shutdown
+ # and the creation and cleanup of our top-level memory pool.
+ svn.core.run_app(do_status, os.path.normpath(args[0]), verbose)
</programlisting>
</example>
- <para>非常不幸，Subversion的语言绑定缺乏对核心Subversion模块的关注，但是，使用Python、Perl和Java创建有功能的邦定取得了显著的成就。一旦你的SWIG接口文件正确的配置，对于SWIG支持的语言（我们当前包括的版本有C#、Guile、Java、MzScheme、OCaml、Perl、PHP、Python、Ruby和Tcl）的特定语言绑定的包裹器的生成理论上是非常琐碎的。但是，对复杂API还是需要一些额外的的补充，SWIG需要帮助归纳。对于SWIG的更多信息，见这个项目的网站<systemitem
- class="url">http://www.swig.org/</systemitem>。
- </para>
+ <para>非常不幸，Subversion的语言绑定缺乏对核心Subversion模块的关注，但是，
+ However, there have been significant efforts towards creating
+ functional bindings for Python, Perl, and Ruby. To some extent,
+ the work done preparing the SWIG interface files for the these
+ languages is reusable in efforts to generate bindings for other
+ languages supported by SWIG (which includes versions of C#,
+ Guile, Java, MzScheme, OCaml, PHP, Tcl, and others).
+ However, some extra programming is required to compensate for
+ complex APIs that SWIG needs some help interfacing with. For
+ more information on SWIG itself, see the project's website at
+ <ulink url="http://www.swig.org/"/>.</para>
</sect2>
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 3: INSIDE THE WORKING COPY ADMINISTRATION AREA *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-8-sect-3">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.developer.insidewc">
<title>进入工作拷贝的管理区</title>
<para>像我们前面提到的，每个Subversion工作拷贝包含了一个特别的子目录叫做<filename>.svn</filename>，这个目录包含了关于工作拷贝目录的管理数据，Subversion使用<filename>.svn</filename>中的信息来追踪如下的数据：
@@ -576,8 +714,8 @@
<para>然而<filename>.svn</filename>目录中还有一些其他的数据，我们会考察一些最重要的项目。
</para>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-3.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.insidewc.entries">
<title>条目文件</title>
<para>或许<filename>.svn</filename>目录中最重要的单个文件就是<filename>entries</filename>了，这个条目文件是一个XML文档，包含了关于工作拷贝中的版本化的资源的大多数管理性信息，这个文件保留了版本库URL、原始修订版本、可知的最后提交信息（作者、修订版本和时间戳）和本地拷贝历史—实际上是Subversion客户端关于一个版本化（或者是将要版本化的）资源的所有感兴趣的信息！</para>
@@ -593,7 +731,7 @@
<para>如下是一个实际条目文件的例子：
</para>
- <example id="svn-ch-8-sect-3-ex-1">
+ <example id="svn.developer.insidewc.entries.ex-1">
<title>典型的<filename>.svn/entries</filename>文件内容</title>
<programlisting>
<?xml version="1.0" encoding="utf-8"?>
@@ -602,30 +740,34 @@
<entry
committed-rev="1"
name=""
- committed-date="2002-09-24T17:12:44.064475Z"
- url="http://svn.red-bean.com/tests/.greek-repo/A/D"
+ committed-date="2005-04-04T13:32:28.526873Z"
+ url="http://svn.red-bean.com/repos/greek-tree/A/D"
+ last-author="jrandom"
kind="dir"
+ uuid="4e820d15-a807-0410-81d5-aa59edf69161"
revision="1"/>
<entry
+ name="lambda"
+ copied="true"
+ kind="file"
+ copyfrom-rev="1"
+ schedule="add"
+ copyfrom-url="http://svn.red-bean.com/repos/greek-tree/A/B/lambda"/>
+<entry
committed-rev="1"
name="gamma"
- text-time="2002-09-26T21:09:02.000000Z"
- committed-date="2002-09-24T17:12:44.064475Z"
- checksum="QSE4vWd9ZM0cMvr7/+YkXQ=="
+ text-time="2005-12-11T16:32:46.000000Z"
+ committed-date="2005-04-04T13:32:28.526873Z"
+ checksum="ada10d942b1964d359e048dbacff3460"
+ last-author="jrandom"
kind="file"
- prop-time="2002-09-26T21:09:02.000000Z"/>
+ prop-time="2005-12-11T16:32:45.000000Z"/>
<entry
name="zeta"
kind="file"
schedule="add"
revision="0"/>
<entry
- url="http://svn.red-bean.com/tests/.greek-repo/A/B/delta"
- name="delta"
- kind="file"
- schedule="add"
- revision="0"/>
-<entry
name="G"
kind="dir"/>
<entry
@@ -645,8 +787,8 @@
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-3.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.insidewc.base-and-props">
<title>原始拷贝和属性文件</title>
<para>如我们前面提到的，<filename>.svn</filename>也包含了一些原始的<quote>text-base</quote>文件版本，可以在<filename>.svn/text-base</filename>看到。这些原始文件的好处是多方面的—察看本地修改和区别不需要经过网络访问，减少传递修改时的数据—但是随之而来的代价是每个版本化的文件都在磁盘至少保存两次，现在看来这是对大多数文件可以忽略不计的一个惩罚。但是，当你版本控制的文件增多之后形势会变得很严峻，我们已经注意到了应该可以选择使用<quote>text-base</quote>，但是具有讽刺意味的是，当版本化文件增大时，<quote>text-base</quote>文件的存在会更加重要—谁会希望在提交一个小修改时在网络上传递一个大文件？
@@ -657,15 +799,14 @@
</sect2>
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 4: WEBDAV *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-8-sect-4">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.developer.webdav">
<title>WebDAV</title>
<para>WebDAV（<quote>Web-based Distributed Authoring
- and Versioning</quote>的缩写）是一个标准HTTP协议的扩展，把web变成一个可读写的媒体，作为当今基本的只读媒体的替代。原理就是目录和文件时可以共享的—都是可读写的对象—通过web。RFCs2518和3253描述了WebDAV/DeltaV 对于HTTP的扩展，存放于（随之有许多其它有用的信息）<systemitem
- class="url">http://www.webdav.org/</systemitem>。</para>
+ and Versioning</quote>的缩写）是一个标准HTTP协议的扩展，把web变成一个可读写的媒体，作为当今基本的只读媒体的替代。原理就是目录和文件时可以共享的—都是可读写的对象—通过web。RFCs2518和3253描述了WebDAV/DeltaV 对于HTTP的扩展，存放于（随之有许多其它有用的信息）<ulink url="http://www.webdav.org/"/>。</para>
<para>已经有一些操作系统文件浏览器可以使用WebDAV装配网络目录，在Win32中，Windows浏览器可以像普通共享文件夹一样浏览叫做网络文件夹（只是一个设置好WebDAV的网络位置）的目录，在Mac OS X也有这个能力，就像Nautilus和Konqueror作的（分别对应GNOME和KDE）。
</para>
@@ -673,13 +814,13 @@
<para>这些是如何应用到Subversion中的呢？mod_dav_svn的Apache模块使用HTTP，通过WebDAV和DeltaV扩展，作为它的网络协议之一，Subversion使用mod_dav_svn在Subversion的版本概念和RFCs 2518和3253对应部分建立影射。
</para>
- <para>关于WebDAV的完全讨论，工作原理和Subversion如何使用，可以看<xref linkend="svn-ap-c"/>。在其他事情中，附录讨论了Subversion与一般的WebDAV规范结合的程度，和这些是如何影响普通WebDAV客户端的交互性。</para>
+ <para>关于WebDAV的完全讨论，工作原理和Subversion如何使用，可以看<xref linkend="svn.webdav"/>。在其他事情中，附录讨论了Subversion与一般的WebDAV规范结合的程度，和这些是如何影响普通WebDAV客户端的交互性。</para>
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 5: PROGRAMMING WITH MEMORY POOLS *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-8-sect-5">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.developer.pools">
<title>使用内存池编程</title>
<para>几乎每一个使用过C语言的开发者曾经感叹令人畏缩的内存管理，分配足够的内存，并且追踪内存的分配，在不需要时释放内存—这个任务会非常复杂。当然，如果没有正确地做到这一点会导致程序毁掉自己，或者更加严重一点，把电脑搞瘫。幸运的是，Subversion所依赖的APR库为了移植性提供了<structname>apr_pool_t</structname>类型，代表了应用可以分配内存的池。
@@ -694,7 +835,7 @@
<para>尽管池帮助我们基本的内存管理，池的创建确实投射出了循环和迭代场景，因为反复在循环中经常没有界限，在深度迭代中，一定区域的内存消耗变得不可预料，很幸运，使用嵌套的内存池可以简单的管理这种潜在的混乱情形，下面的例子描述了在这个情形下嵌套池的基本使用非常平常—迭代的对目录树的遍历，对树上的每一个部分做一些任务。
</para>
- <example id="svn-ch-8-sect-5-ex-1">
+ <example id="svn.developer.pools.ex-1">
<title>有效地池使用</title>
<programlisting>
/* Recursively crawl over DIRECTORY, adding the paths of all its file
@@ -786,18 +927,17 @@
</sect1>
- <!-- ******************************************************************* -->
- <!-- *** SECTION 6: CONTRIBUTING TO SUBVERSION *** -->
- <!-- ******************************************************************* -->
- <sect1 id="svn-ch-8-sect-6">
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.developer.contrib">
<title>为Subversion做贡献</title>
- <para>Subversion项目的官方信息源当然是项目的网站<systemitem
- class="url">http://subversion.tigris.org/</systemitem>。这里你可以发现如何得到源代码和参与到讨论列表。Subversion社区一致欢迎新成员，如果你有兴趣通过贡献源代码来参与到社区，以下是一下作为开始的提示。
+ <para>Subversion项目的官方信息源当然是项目的网站<ulink url="http://subversion.tigris.org/"/>。这里你可以发现如何得到源代码和参与到讨论列表。Subversion社区一致欢迎新成员，如果你有兴趣通过贡献源代码来参与到社区，以下是一下作为开始的提示。
</para>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-6.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.contrib.join">
<title>加入社区</title>
<para>加入社区的第一步是关注最新发生的事情，最有效的办法是订阅主要的开发邮件列表（<email>dev at subversion.tigris.org</email>）和提交邮件列表（<email>svn at subversion.tigris.org</email>）。通过轻松的跟踪这些列表，你可以参与最重要的设计讨论，并且可以看到实际发生效果的Subversion代码，并且可以见证这些修改并提出修改建议。这些基于邮件列表的讨论是我们Subversion开发最主要的交流媒体。如果你对其他Subversion相关的列表有兴趣，可以查看本网站的邮件列表部分。</para>
@@ -806,15 +946,15 @@
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-6.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.contrib.get-code">
<title>取得源代码</title>
<para>为了编辑源代码，你需要得到源代码，这意味着你需要从Subversion源代码版本库检出一个工作拷贝，听起来如此直接，这个任务可能有一点微妙。因为Subversion的源代码使用Subversion本身版本管理，你实际上需要使用别的方法得到工作的Subversion客户端来启动这个过程。最通常的方法是下载最新的二进制分发版本（如果有你的平台的版本存在），或者是下载最新的源程序包并且自己编译Subversion客户端，如果你从源代码编译，确定要阅读源代码顶级目录的<filename>INSTALL</filename>文件作为指导。
</para>
- <para>在你有了工作的Subversion客户端后，你可以泰然自若的从Subversion源代码版本库<systemitem
- class="url">http://svn.collab.net/repos/svn/trunk/</systemitem>检出一个工作拷贝：
+ <para>在你有了工作的Subversion客户端后，你可以泰然自若的从Subversion源代码版本库<ulink
+ url="http://svn.collab.net/repos/svn/trunk/"/>检出一个工作拷贝：
<footnote>
<para>注意上面例子中检出的URL并不是以<literal>svn</literal>结尾，而是它的一个叫做<literal>trunk</literal>的子目录，可以看我们对Subversion的分支和标签模型的讨论来理解背后的原因。
</para>
@@ -822,11 +962,11 @@
<screen>
$ svn checkout http://svn.collab.net/repos/svn/trunk subversion
-A subversion/HACKING
-A subversion/INSTALL
-A subversion/README
-A subversion/autogen.sh
-A subversion/build.conf
+A subversion/HACKING
+A subversion/INSTALL
+A subversion/README
+A subversion/autogen.sh
+A subversion/build.conf
…
</screen>
@@ -835,20 +975,33 @@
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-6.3">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.contrib.hacking">
<title>开始熟悉社区政策</title>
- <para>现在你有了包含最新Subversion源代码的工作拷贝，你一定希望来通过工作拷贝顶级目录下的<filename>HACKING</filename>文件来做一次浏览。这个<filename>HACKING</filename>文件包含了如何对Subversion做贡献的说明，包括如何正确地格式化代码与余下的代码基保持一致性，如何使用有效的提交日志描述你的被提议修改，如何测试修改，等等。对Subversion源代码的提交特权是需要争取得到的—被精英所管理。
+ <para>Now that you have a working copy containing the latest
+ Subversion source code, you will most certainly want to take a
+ cruise through the <quote>Hacker's Guide to Subversion</quote>,
+ which is available either as the
+ <filename>www/hacking.html</filename> file in the working copy,
+ or on the Subversion website at <ulink
+ url="http://subversion.tigris.org/hacking.html"/>. This guide
+ contains general instructions for contributing to Subversion,
+ including how to properly format your source code for
+ consistency with the rest of the codebase, how to describe your
+ proposed changes with an effective change log message, how to
+ test your changes, and so on. Commit privileges on the
+ Subversion source repository are earned—a government by
+ meritocracy.
<footnote>
<para>浅薄的看起来这像是某种高人一等的优越感，<quote>赢得你的提交特权</quote>这个概念关于效率—检查和应用别人的修改是否安全和有用会花费大量的时间和精力，与之相比的是取消危险的代码的潜在代价。</para>
</footnote>
- <filename>HACKING</filename>文件是一个无价的资源，它可以确保你被提议作的修改能够取得承认，而不会因为技术原因被拒绝。</para>
+ <quote>Hacker's Guide</quote>文件是一个无价的资源，它可以确保你被提议作的修改能够取得承认，而不会因为技术原因被拒绝。</para>
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-6.4">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.contrib.code-and-test">
<title>作出修改并测试</title>
<para>当理解了代码和社区政策，你已经准备好了作出修改，最好是努力作出小的但是相关的修改，即使在处理大的任务阶段，不要选择作出巨大的扫除试的修改。如果你搞乱最少的代码来完成修改，你被提议的修改就会很容易理解（而且因此应该很容易去审核）。当完成了每个提议的修改集，你的Subversion树一定要处于编译无警告的状态。</para>
@@ -867,8 +1020,8 @@
</sect2>
- <!-- ***************************************************************** -->
- <sect2 id="svn-ch-8-sect-6.5">
+ <!-- =============================================================== -->
+ <sect2 id="svn.developer.contrib.submit">
<title>贡献你的修改</title>
<para>当完成了对源代码的修改，写一个干净的和细致的日志信息来描述那些修改和原因。然后，发送一个包含日志信息和<command>svn diff</command>（在Subversion工作拷贝顶级目录运行）输出的邮件到开发者列表。如果社区成员认为你的修改可以接受，一些有提交权限（允许在Subversion源代码版本库提交新的修订版本）的用户会添加你的新的修改到公共源代码树。回想对版本库直接的提交权限是赋予那些展现能力的人—如果你展示了对Subversion的理解，编程能力，和<quote>团队精神</quote>，你会很可能授予那个权限。</para>
Modified: trunk/src/zh/book/ch09.xml
==============================================================================
--- trunk/src/zh/book/ch09.xml (original)
+++ trunk/src/zh/book/ch09.xml Wed Jan 25 01:01:34 2006
@@ -1,4 +1,4 @@
-<chapter id="svn-ch-9">
+<chapter id="svn.ref">
<title>Subversion完全参考</title>
<simplesect>
@@ -7,9 +7,9 @@
</simplesect>
<!-- ================================================================= -->
- <!-- ======================== SECTION 1 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-9-sect-1">
+ <!-- ================================================================= -->
+ <sect1 id="svn.ref.svn">
<title>Subversion命令行客户端：<command>svn</command></title>
<para>为了使用命令行客户端，只需要输入<command>svn</command>和它的子命令<footnote>
@@ -24,9 +24,10 @@
$ svn status -v myfile
</screen>
- <para>你可以在<xref linkend="svn-ch-3"/>发现更多使用客户端命令的例子，以及<xref linkend="svn-ch-7-sect-2"/>中的管理属性的命令。</para>
+ <para>你可以在<xref linkend="svn.tour"/>发现更多使用客户端命令的例子，以及<xref linkend="svn.advanced.props"/>中的管理属性的命令。</para>
- <sect2 id="svn-ch-9-sect-1.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.ref.svn.sw">
<title><command>svn</command>选项</title>
<para>虽然Subversion的子命令有一些不同的选项，但有的选项是全局的—也就是说，每个选项保证是表示同样的事情，而不管是哪个子命令使用的。举个例子，<option>--verbose</option>（<option>-v</option>）一直意味着<quote>冗长输出</quote>，而不管使用它的命令是什么。</para>
@@ -138,6 +139,14 @@
</varlistentry>
<varlistentry>
+ <term><option>--ignore-externals</option></term>
+ <listitem>
+ <para>Tells Subversion to ignore external definitions and
+ the external working copies managed by them.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--incremental</option></term>
<listitem>
<para>打印适合串联的输出格式。</para>
@@ -145,6 +154,15 @@
</varlistentry>
<varlistentry>
+ <term><option>--limit</option>
+ <replaceable>NUM</replaceable></term>
+ <listitem>
+ <para>Show only the first <replaceable>NUM</replaceable>
+ log messages.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--message</option> (<option>-m</option>)
<replaceable>MESSAGE</replaceable>
</term>
@@ -180,6 +198,17 @@
</varlistentry>
<varlistentry>
+ <term><option>--no-diff-added</option></term>
+ <listitem>
+ <para>Prevents Subversion from printing differences for
+ added files. The default behavior when you add a file is
+ for <command>svn diff</command> to print the same
+ differences that you would see if you had added the entire
+ contents of an existing (empty) file.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--no-diff-deleted</option></term>
<listitem>
<para>防止Subversion打印删除文件的区别信息，缺省的行为方式是当你删除了一个文件后运行<command>svn diff</command>打印的区别与删除文件所有的内容得到的结果一样。
@@ -191,8 +220,18 @@
<term><option>--no-ignore</option></term>
<listitem>
<para>在状态列表中显示<literal>global-ignores</literal>配置选项或者是<literal>svn:ignore</literal>属性忽略的文件。见<xref
- linkend="svn-ch-7-sect-1.3.2"/>和<xref
- linkend="svn-ch-7-sect-2.3.3"/>查看详情。</para>
+ linkend="svn.advanced.confarea.opts.config"/>和<xref
+ linkend="svn.advanced.props.special.ignore"/>查看详情。</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--no-unlock</option></term>
+ <listitem>
+ <para>Don't automatically unlock files (the default commit
+ behavior is to unlock all files listed as part of the
+ commit). See <xref linkend="svn.advanced.locking"/> for
+ more information.</para>
</listitem>
</varlistentry>
@@ -271,7 +310,7 @@
$ svn log -r 1729:{2002-02-17}
</screen>
- <para>见<xref linkend="svn-ch-3-sect-3.2"/>查看更多信息。</para>
+ <para>见<xref linkend="svn.tour.revs.keywords"/>查看更多信息。</para>
</listitem>
</varlistentry>
@@ -279,7 +318,7 @@
<term><option>--revprop</option></term>
<listitem>
<para>操作是针对一个修订版本的属性而不是一个文件或目录的属性。这个开关需要你也要通过<option>--revision</option>（<option>-r</option>）传递一个修订版本号，见<xref
- linkend="svn-ch-5-sect-1.2"/>关于未版本化的属性的细节。
+ linkend="svn.reposadmin.basics.revprops"/>关于未版本化的属性的细节。
</para>
</listitem>
</varlistentry>
@@ -348,10 +387,11 @@
</sect2>
- <sect2 id="svn-ch-9-sect-1.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.ref.svn.c">
<title><command>svn</command>子命令</title>
- <refentry id="svn-ch-9-sect-1.2-re-add">
+ <refentry id="svn.ref.svn.c.add">
<refnamediv>
<refname>svn add</refname>
<refpurpose>添加文件、目录或符号链。</refpurpose>
@@ -432,21 +472,20 @@
A foo.c
A somedir/bar.c
A otherdir/docs/baz.doc
-[...]
+…
</screen>
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-blame">
+ <refentry id="svn.ref.svn.c.blame">
<refnamediv>
<refname>svn blame</refname>
<refpurpose>显示特定文件和URL内嵌的作者和修订版本信息。</refpurpose>
</refnamediv>
<refsect1>
<title>概要</title>
- <programlisting>svn blame TARGET...</programlisting>
+ <programlisting>svn blame TARGET[@REV]...</programlisting>
</refsect1>
<refsect1>
<title>描述</title>
@@ -497,8 +536,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-cat">
+ <refentry id="svn.ref.svn.c.cat">
<refnamediv>
<refname>svn cat</refname>
<refpurpose>输出特定文件或URL的内容。</refpurpose>
@@ -570,8 +608,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-checkout">
+ <refentry id="svn.ref.svn.c.checkout">
<refnamediv>
<refname>svn checkout</refname>
<refpurpose>从版本库取出一个工作拷贝。</refpurpose>
@@ -583,7 +620,7 @@
<refsect1>
<title>描述</title>
- <para>从版本库取出一个工作拷贝，如果省略<replaceable>PATH</replaceable>，URL的基名称会作为目标，如果给定多个URL，每一个都会检出到PATH的子目录，使用URL基名称的子目录名称。
+ <para>从版本库取出一个工作拷贝，如果省略<replaceable>PATH</replaceable>，URL的基名称会作为目标，如果给定多个URL，每一个都会检出到<replaceable>PATH</replaceable>的子目录，使用URL基名称的子目录名称。
</para>
</refsect1>
@@ -614,6 +651,7 @@
--password PASS
--no-auth-cache
--non-interactive
+--ignore-externals
--config-dir DIR
</screen>
</refsect1>
@@ -689,8 +727,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-cleanup">
+ <refentry id="svn.ref.svn.c.cleanup">
<refnamediv>
<refname>svn cleanup</refname>
<refpurpose>递归清理工作拷贝。</refpurpose>
@@ -702,8 +739,7 @@
<refsect1>
<title>描述</title>
- <para>递归清理工作拷贝，删除未完成的操作锁定。如果你得到一个<quote>工作拷贝已锁定</quote>的错误，运行这个命令可以删除无效的锁定，让你的工作拷贝再次回到可用的状态。见<xref
- linkend="svn-ap-b"/>。
+ <para>递归清理工作拷贝，删除未完成的操作锁定。如果你得到一个<quote>工作拷贝已锁定</quote>的错误，运行这个命令可以删除无效的锁定，让你的工作拷贝再次回到可用的状态。
</para>
<para>如果，因为一些原因，运行外置的区别程序（例如，用户输入或是网络错误）有时候会导致一个<command>svn update</command>失败，使用<option>--diff3-cmd</option>选项可以完全清除你的外置区别程序所作的合并，你也可以使用<option>--config-dir</option>指定任何配置目录，但是你应该不会经常使用这些选项。</para>
@@ -738,7 +774,7 @@
<refsect1>
<title>例子</title>
- <para><command>svn cleanup</command>没有输出，没有太多的例子，如果你没有传递路径，会使用<quote><filename>.</filename></quote>。</para>
+ <para><command>svn cleanup</command>没有输出，没有太多的例子，如果你没有传递<replaceable>PATH</replaceable>，会使用<quote><filename>.</filename></quote>。</para>
<screen>
$ svn cleanup
@@ -749,8 +785,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-commit">
+ <refentry id="svn.ref.svn.c.commit">
<refnamediv>
<refname>svn commit</refname>
<refpurpose>将修改从工作拷贝发送到版本库。</refpurpose>
@@ -763,8 +798,13 @@
<title>描述</title>
<para>将修改从工作拷贝发送到版本库。如果你没有使用<option>--file</option>或<option>--message</option>提供一个提交日志信息，<command>svn</command>会启动你的编辑器来编写一个提交信息，见<xref
- linkend="svn-ch-7-sect-1.3.2"/>的<literal>editor-cmd</literal>小节。</para>
+ linkend="svn.advanced.confarea.opts.config"/>的<literal>editor-cmd</literal>小节。</para>
+ <para><command>svn commit</command> will send found lock
+ tokens and release locks on all
+ <replaceable>PATHS</replaceable> committed (recursively)
+ unless <option>--no-unlock</option> is passed.</para>
+
<tip>
<para>如果你开始一个提交并且Subversion启动了你的编辑器来编辑提交信息，你仍可以退出而不会提交你的修改，如果你希望取消你的提交，只需要退出编辑器而不保存你的提交信息，Subversion会提示你是选择取消提交、空信息继续还是重新编辑信息。</para>
</tip>
@@ -795,6 +835,7 @@
--message (-m) TEXT
--file (-F) FILE
--quiet (-q)
+--no-unlock
--non-recursive (-N)
--targets FILENAME
--force-log
@@ -853,8 +894,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-copy">
+ <refentry id="svn.ref.svn.c.copy">
<refnamediv>
<refname>svn copy</refname>
<refpurpose>拷贝工作拷贝的一个文件或目录到版本库。</refpurpose>
@@ -1003,8 +1043,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-delete">
+ <refentry id="svn.ref.svn.c.delete">
<refnamediv>
<refname>svn delete</refname>
<refpurpose>从工作拷贝或版本库删除一个项目。</refpurpose>
@@ -1095,8 +1134,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-diff">
+ <refentry id="svn.ref.svn.c.diff">
<refnamediv>
<refname>svn diff</refname>
<refpurpose>比较两条路径的区别。</refpurpose>
@@ -1281,8 +1319,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-export">
+ <refentry id="svn.ref.svn.c.export">
<refnamediv>
<refname>svn export</refname>
<refpurpose>导出一个干净的目录树。</refpurpose>
@@ -1290,7 +1327,7 @@
<refsect1>
<title>概要</title>
<programlisting>svn export [-r REV] URL[@PEGREV] [PATH]</programlisting>
- <programlisting>svn export PATH1[@PEGREV] PATH2</programlisting>
+ <programlisting>svn export [-r REV] PATH1[@PEGREV] [PATH2]</programlisting>
</refsect1>
<refsect1>
<title>描述</title>
@@ -1326,8 +1363,10 @@
--password PASS
--no-auth-cache
--non-interactive
+--non-recursive
--config-dir DIR
--native-eol EOL
+--ignore-externals
</screen>
</refsect1>
@@ -1365,10 +1404,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
-
-
- <refentry id="svn-ch-9-sect-1.2-re-help">
+ <refentry id="svn.ref.svn.c.help">
<refnamediv>
<refname>svn help</refname>
<refpurpose>帮助！</refpurpose>
@@ -1408,11 +1444,10 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-import">
+ <refentry id="svn.ref.svn.c.import">
<refnamediv>
<refname>svn import</refname>
- <refpurpose>递归提交一个路径的拷贝到URL。</refpurpose>
+ <refpurpose>递归提交一个路径的拷贝到版本库。</refpurpose>
</refnamediv>
<refsect1>
<title>概要</title>
@@ -1457,6 +1492,7 @@
--config-dir DIR
--auto-props
--no-auto-props
+--ignore-externals
</screen>
</refsect1>
@@ -1488,26 +1524,27 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-info">
+ <refentry id="svn.ref.svn.c.info">
<refnamediv>
<refname>svn info</refname>
- <refpurpose>打印PATH的信息。</refpurpose>
+ <refpurpose>显示本地或远程条目的信息。</refpurpose>
</refnamediv>
<refsect1>
<title>概要</title>
- <programlisting>svn info [PATH...]</programlisting>
+ <programlisting>svn info [TARGET...]</programlisting>
</refsect1>
<refsect1>
<title>描述</title>
- <para>打印你的工作拷贝的路径信息，包括：</para>
+ <para>打印你的工作拷贝路径和URL的信息，包括：</para>
<itemizedlist>
<listitem><para>路经</para></listitem>
<listitem><para>名称</para></listitem>
<listitem><para>URL</para></listitem>
<listitem><para>修订版本</para></listitem>
+ <listitem><para>版本库的根</para></listitem>
+ <listitem><para>版本库的UUID</para></listitem>
<listitem><para>节点类型</para></listitem>
<listitem><para>最后修改的作者</para></listitem>
<listitem><para>最后修改的修订版本</para></listitem>
@@ -1515,6 +1552,9 @@
<listitem><para>最后更新的文本</para></listitem>
<listitem><para>最后更新的属性</para></listitem>
<listitem><para>核对</para></listitem>
+ <listitem><para>锁定令牌</para></listitem>
+ <listitem><para>锁定拥有者</para></listitem>
+ <listitem><para>锁定创建时间</para></listitem>
</itemizedlist>
</refsect1>
@@ -1530,7 +1570,7 @@
<refsect1>
<title>是否访问版本库</title>
- <para>无</para>
+ <para>对URL操作时访问</para>
</refsect1>
<refsect1>
@@ -1539,6 +1579,7 @@
<screen>
--targets FILENAME
--recursive (-R)
+--revision (-r)
--config-dir DIR
</screen>
</refsect1>
@@ -1553,6 +1594,8 @@
Path: foo.c
Name: foo.c
URL: http://svn.red-bean.com/repos/test/foo.c
+Repository Root: http://svn.red-bean.com/repos/test
+Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25
Revision: 4417
Node Kind: file
Schedule: normal
@@ -1568,8 +1611,10 @@
<screen>
$ svn info vendors
-Path: trunk
+Path: vendors
URL: http://svn.red-bean.com/repos/test/vendors
+Repository Root: http://svn.red-bean.com/repos/test
+Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25
Revision: 19
Node Kind: directory
Schedule: normal
@@ -1577,12 +1622,37 @@
Last Changed Rev: 19
Last Changed Date: 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003)
</screen>
+
+
+ <para><command>svn info</command> also acts on URLs (also
+ note that the file readme.doc in this example is locked,
+ so lock information is also provided):</para>
+
+ <screen>
+$ svn info http://svn.red-bean.com/repos/test/readme.doc
+Path: readme.doc
+Name: readme.doc
+URL: http://svn.red-bean.com/repos/test/readme.doc
+Repository Root: http://svn.red-bean.com/repos/test
+Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25
+Revision: 1
+Node Kind: file
+Schedule: normal
+Last Changed Author: sally
+Last Changed Rev: 42
+Last Changed Date: 2003-01-14 23:21:19 -0600 (Tue, 14 Jan 2003)
+Text Last Updated: 2003-01-14 23:21:19 -0600 (Tue, 14 Jan 2003)
+Checksum: d41d8cd98f00b204e9800998ecf8427e
+Lock Token: opaquelocktoken:14011d4b-54fb-0310-8541-dbd16bd471b2
+Lock Owner: harry
+Lock Created: 2003-01-15 17:35:12 -0600 (Wed, 15 Jan 2003)
+</screen>
+
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-list">
+ <refentry id="svn.ref.svn.c.list">
<refnamediv>
<refname>svn list</refname>
<refpurpose>列出版本库目录的条目。</refpurpose>
@@ -1663,13 +1733,107 @@
</screen>
<para>更多细节见<xref
- linkend="svn-ch-3-sect-6.4"/>。</para>
+ linkend="svn.tour.history.list"/>。</para>
+
+ </refsect1>
+ </refentry>
+
+
+ <refentry id="svn.ref.svn.c.lock">
+ <refnamediv>
+ <refname>svn lock</refname>
+ <refpurpose>Lock working copy paths or URLs in the
+ repository, so that no other user can commit changes to
+ them.</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Synopsis</title>
+ <programlisting>svn lock TARGET...</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+
+ <para>Lock each <replaceable>TARGET</replaceable>. If any
+ <replaceable>TARGET</replaceable> is already locked by
+ another user, print a warning and continue locking the
+ rest of the <replaceable>TARGET</replaceable>s. Use
+ <option>--force</option> to steal a lock from another user
+ or working copy.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Alternate Names</title>
+ <para>None</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Changes</title>
+ <para>Working Copy, Repository</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Accesses Repository</title>
+ <para>Yes</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Switches</title>
+
+ <screen>
+--targets ARG
+--message (-m) ARG
+--file (-F) ARG
+--force-log
+--encoding ARG
+--username ARG
+--password ARG
+--no-auth-cache
+--non-interactive
+--config-dir ARG
+--force
+</screen>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <para>Lock two files in your working copy:</para>
+
+ <screen>
+
+$ svn lock tree.jpg house.jpg
+'tree.jpg' locked by user 'harry'.
+'house.jpg' locked by user 'harry'.
+</screen>
+
+ <para>Lock a file in your working copy that is currently
+ locked by another user:</para>
+
+ <screen>
+$ svn lock tree.jpg
+svn: warning: Path '/tree.jpg is already locked by user 'harry in \
+ filesystem '/svn/repos/db'
+
+$ svn lock --force foo
+'tree.jpg' locked by user 'sally'.
+</screen>
+
+ <para>Lock a file without a working copy:</para>
+
+ <screen>
+$ svn lock http://svn.red-bean.com/repos/test/tree.jpg
+'tree.jpg' locked by user 'sally'.
+</screen>
+
+ <para>For further details, see <xref
+ linkend="svn.advanced.locking"/>.</para>
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-log">
+
+ <refentry id="svn.ref.svn.c.log">
<refnamediv>
<refname>svn log</refname>
<refpurpose>显示提交日志信息。</refpurpose>
@@ -1718,6 +1882,7 @@
--targets FILENAME
--stop-on-copy
--incremental
+--limit NUM
--xml
--username USER
--password PASS
@@ -1788,7 +1953,7 @@
…
</screen>
- <para>当你想连接多个队日志命令的调用结果，你会希望使用<option>--incremental</option>选项。<command>svn
+ <para>当你想¿ž接多个队日志命令的调用结果，你会希望使用<option>--incremental</option>选项。<command>svn
log</command>通常会在日志信息的开头和每一小段间打印一行虚线，如果你对一段修订版本运行<command>svn log</command>，你会得到下面的结果：</para>
<screen>
$ svn log -r 14:15
@@ -1869,8 +2034,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-merge">
+ <refentry id="svn.ref.svn.c.merge">
<refnamediv>
<refname>svn merge</refname>
<refpurpose>应用两组源文件的差别到工作拷贝路径。</refpurpose>
@@ -1884,10 +2048,10 @@
<refsect1>
<title>描述</title>
- <para>第一种形式，源URL用修订版本号<replaceable>N</replaceable>和<replaceable>M</replaceable>指定，这是要比较的两组源文件，如果省略修订版本号，缺省是<literal>HEAD</literal>。
+ <para>第一种和第二种形式里，源路径（第一种是URL，第二种是工作拷贝路径）用修订版本号<replaceable>N</replaceable>和<replaceable>M</replaceable>指定，这是要比较的两组源文件，如果省略修订版本号，缺省是<literal>HEAD</literal>。
</para>
- <para>第二种形式，<replaceable>SOURCE</replaceable>可以是URL或者工作拷贝项目，与之对应的URL会被使用。在修订版本号<replaceable>N</replaceable>和<replaceable>M</replaceable>的URL定义了要比较的两组源。</para>
+ <para>第三种形式，<replaceable>SOURCE</replaceable>可以是URL或者工作拷贝项目，与之对应的URL会被使用。在修订版本号<replaceable>N</replaceable>和<replaceable>M</replaceable>的URL定义了要比较的两组源。</para>
<para><replaceable>WCPATH</replaceable>是接收变化的工作拷贝路径，如果省略<replaceable>WCPATH</replaceable>，会假定缺省值<quote><filename>.</filename></quote>，除非源有相同基本名称与<quote><filename>.</filename></quote>中的某一文件名字匹配：在这种情况下，区别会应用到那个文件。
</para>
@@ -1963,8 +2127,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-mkdir">
+ <refentry id="svn.ref.svn.c.mkdir">
<refnamediv>
<refname>svn mkdir</refname>
<refpurpose>创建一个纳入版本控制的新目录。</refpurpose>
@@ -2036,8 +2199,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-move">
+ <refentry id="svn.ref.svn.c.move">
<refnamediv>
<refname>svn move</refname>
<refpurpose>移动一个文件或目录。</refpurpose>
@@ -2142,8 +2304,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-propdel">
+ <refentry id="svn.ref.svn.c.propdel">
<refnamediv>
<refname>svn propdel</refname>
<refpurpose>删除一个项目的一个属性。</refpurpose>
@@ -2210,8 +2371,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-propedit">
+ <refentry id="svn.ref.svn.c.propedit">
<refnamediv>
<refname>svn propedit</refname>
<refpurpose>修改一个或多个版本控制之下文件的属性。</refpurpose>
@@ -2277,8 +2437,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-propget">
+ <refentry id="svn.ref.svn.c.propget">
<refnamediv>
<refname>svn propget</refname>
<refpurpose>打印一个属性的值。</refpurpose>
@@ -2292,7 +2451,7 @@
<title>描述</title>
<para>打印一个文件、目录或修订版本的一个属性的值，第一种形式是打印工作拷贝中一个或多个项目的版本化的属性，第二种形式是远程打印版本库修订版本的未版本化的属性。属性的详情见<xref
- linkend="svn-ch-7-sect-2"/>。</para>
+ linkend="svn.advanced.props"/>。</para>
</refsect1>
<refsect1>
@@ -2349,8 +2508,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-proplist">
+ <refentry id="svn.ref.svn.c.proplist">
<refnamediv>
<refname>svn proplist</refname>
<refpurpose>列出所有的属性。</refpurpose>
@@ -2427,8 +2585,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-propset">
+ <refentry id="svn.ref.svn.c.propset">
<refnamediv>
<refname>svn propset</refname>
<refpurpose>设置文件、目录或者修订版本的属性PROPNAME为PROPVAL。</refpurpose>
@@ -2447,7 +2604,7 @@
<tip>
<para>Subversion有一系列<quote>特殊的</quote>影响行为方式的属性，关于这些属性的详情请见<xref
- linkend="svn-ch-7-sect-2.3"/>。
+ linkend="svn.advanced.props.special"/>。
</para>
</tip>
@@ -2537,15 +2694,14 @@
<note>
<para>缺省，你不可以在Subversion版本库修改修订版本属性，你的版本库管理员必须显示的通过创建一个名字为<literal>pre-revprop-change</literal>的钩子来允许修订版本属性修改，关于钩子脚本的详情请见<xref
- linkend="svn-ch-5-sect-2.1"/>。
+ linkend="svn.reposadmin.create.hooks"/>。
</para>
</note>
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-resolved">
+ <refentry id="svn.ref.svn.c.resolved">
<refnamediv>
<refname>svn resolved</refname>
<refpurpose>删除工作拷贝文件或目录的<quote>冲突</quote>状态。</refpurpose>
@@ -2557,8 +2713,8 @@
<refsect1>
<title>描述</title>
- <para>删除工作拷贝文件或目录的<quote>conflicted</quote>状态。这个程序不是语义上的改变冲突标志，它只是删除冲突相关的人造文件，从而重新允许路径提交；也就是说，它告诉Subversion冲突已经<quote>解决了</quote>。关于解决冲突更深入的考虑可以查看<xref
- linkend="svn-ch-3-sect-5.4"/>。</para>
+ <para>删除工作拷贝文件或目录的<quote>conflicted</quote>状态。这个程序不是语义上的改变冲突标志，它只是删除冲突相关的人造文件，从而重新允许<replaceable>PATH</replaceable>提交；也就是说，它告诉Subversion冲突已经<quote>解决了</quote>。关于解决冲突更深入的考虑可以查看<xref
+ linkend="svn.tour.cycle.resolve"/>。</para>
</refsect1>
<refsect1>
@@ -2614,8 +2770,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-revert">
+ <refentry id="svn.ref.svn.c.revert">
<refnamediv>
<refname>svn revert</refname>
<refpurpose>取消所有的本地编辑。</refpurpose>
@@ -2704,8 +2859,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-status">
+ <refentry id="svn.ref.svn.c.status">
<refnamediv>
<refname>svn status</refname>
<refpurpose>打印工作拷贝文件和目录的状态。</refpurpose>
@@ -2720,7 +2874,7 @@
<para>打印工作拷贝文件和目录的状态。如果没有参数，只会打印本地修改的项目（不会访问版本库），使用<option>--show-updates</option>选项，会添加工作修订版本和服务器过期信息。使用<option>--verbose</option>会打印每个项目的完全修订版本信息。
</para>
- <para>输出的前五列都是一个字符宽，每一列给出了工作拷贝项目的每一方面的信息。
+ <para>输出的前六列都是一个字符宽，每一列给出了工作拷贝项目的每一方面的信息。
</para>
<para>第一列指出一个项目的是添加、删除还是其它的修改。</para>
@@ -2765,7 +2919,8 @@
<varlistentry>
<term>'C'</term>
<listitem>
- <para>项目与从版本库的更新冲突。</para>
+ <para>项目的内容（相对于属性）与更新得到的数据冲突了。
+ </para>
</listitem>
</varlistentry>
@@ -2877,7 +3032,7 @@
</variablelist>
<para>第五列只在项目跳转到相对于它的父目录时出现（见<xref
- linkend="svn-ch-4-sect-5"/>）。
+ linkend="svn.branchmerge.switchwc"/>）。
</para>
<variablelist>
@@ -2898,7 +3053,62 @@
</variablelist>
- <para>过期信息出现在第八列（只在使用<option>--show-updates</option>选项时出现）。</para>
+ <para>The sixth column is populated with lock information.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>' '</term>
+ <listitem>
+ <para>When <option>--show-updates</option> is used,
+ the file is not locked. If
+ <option>--show-updates</option> is
+ <emphasis>not</emphasis> used, this merely means that
+ the file is not locked in this working copy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>K</term>
+ <listitem>
+ <para>File is locked in this working copy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>O</term>
+ <listitem>
+ <para>File is locked either by another user or in
+ another working copy. This only appears when
+ <option>--show-updates</option> is used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>T</term>
+ <listitem>
+ <para>File was locked in this working copy, but the
+ lock has been <quote>stolen</quote>and is invalid.
+ The file is currently locked in the repository. This
+ only appears when <option>--show-updates</option> is
+ used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>B</term>
+ <listitem>
+ <para>File was locked in this working copy, but the
+ lock has been <quote>broken</quote>and is invalid.
+ The file is no longer locked This only appears when
+ <option>--show-updates</option> is used.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+
+ <para>过期信息出现在第七列（只在使用<option>--show-updates</option>选项时出现）。</para>
<variablelist>
@@ -2957,6 +3167,7 @@
--no-auth-cache
--non-interactive
--config-dir
+--ignore-externals
</screen>
</refsect1>
@@ -2999,14 +3210,13 @@
Head revision: 981
</screen>
- <para>关于<command>svn status</command>的更多例子可以见<xref linkend="svn-ch-3-sect-5.3.1"/>。
+ <para>关于<command>svn status</command>的更多例子可以见<xref linkend="svn.tour.cycle.examine.status"/>。
</para>
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-switch">
+ <refentry id="svn.ref.svn.c.switch">
<refnamediv>
<refname>svn switch</refname>
<refpurpose>把工作拷贝更新到别的URL。</refpurpose>
@@ -3023,7 +3233,7 @@
<title>描述</title>
<para>这个子命令更新你的工作拷贝来反映新的URL—通常是一个与你的工作拷贝分享共同祖先的URL，尽管这不是必需的。这是Subversion移动工作拷贝到分支的方式。更深入的了解请见<xref
- linkend="svn-ch-4-sect-5"/>。</para>
+ linkend="svn.branchmerge.switchwc"/>。</para>
</refsect1>
<refsect1>
@@ -3129,8 +3339,94 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-1.2-re-update">
+ <refentry id="svn.ref.svn.c.unlock">
+ <refnamediv>
+ <refname>svn unlock</refname>
+ <refpurpose>Unlock working copy paths or URLs.</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Synopsis</title>
+ <programlisting>svn unlock TARGET...</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+
+ <para>Unlock each <replaceable>TARGET</replaceable>. If any
+ <replaceable>TARGET</replaceable> is either locked by
+ another user or no valid lock token exists in the working
+ copy, print a warning and continue unlocking the rest of
+ the <replaceable>TARGET</replaceable>s. Use
+ <option>--force</option> to break a lock belonging to
+ another user or working copy.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Alternate Names</title>
+ <para>None</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Changes</title>
+ <para>Working Copy, Repository</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Accesses Repository</title>
+ <para>Yes</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Switches</title>
+
+ <screen>
+--targets ARG
+--username ARG
+--password ARG
+--no-auth-cache
+--non-interactive
+--config-dir ARG
+--force
+</screen>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <para>Unlock two files in your working copy:</para>
+
+ <screen>
+
+$ svn unlock tree.jpg house.jpg
+'tree.jpg' unlocked.
+'house.jpg' unlocked.
+</screen>
+
+ <para>Unlock a file in your working copy that is currently
+ locked by another user:</para>
+
+ <screen>
+$ svn unlock tree.jpg
+svn: 'tree.jpg' is not locked in this working copy
+$ svn unlock --force tree.jpg
+'tree.jpg' unlocked.
+</screen>
+
+ <para>Unlock a file without a working copy:</para>
+
+ <screen>
+$ svn unlock http://svn.red-bean.com/repos/test/tree.jpg
+'tree.jpg unlocked.
+</screen>
+
+ <para>For further details, see <xref
+ linkend="svn.advanced.locking"/>.</para>
+
+ </refsect1>
+ </refentry>
+
+
+ <refentry id="svn.ref.svn.c.update">
<refnamediv>
<refname>svn update</refname>
<refpurpose>更新你的工作拷贝。</refpurpose>
@@ -3142,7 +3438,7 @@
<refsect1>
<title>描述</title>
- <para><command>svn update</command>会把版本库的修改带到工作拷贝，如果没有给定修订版本，它会把你的工作拷贝更新到<literal>HEAD</literal>修订版本，否则，它会把工作拷贝更新到你用<option>--revision</option>指定的修订版本。
+ <para><command>svn update</command>会把版本库的修改带到工作拷贝，如果没有给定修订版本，它会把你的工作拷贝更新到<literal>HEAD</literal>修订版本，否则，它会把工作拷贝更新到你用<option>--revision</option>指定的修订版本。为了保持同步，也会删除所有在工作拷贝发现的无效锁定。
</para>
<para>对于每一个更新的项目开头都有一个表示所做动作的字符，这些字符有下面的意思：
@@ -3219,6 +3515,7 @@
--no-auth-cache
--non-interactive
--config-dir DIR
+--ignore-externals
</screen>
</refsect1>
@@ -3237,7 +3534,7 @@
</screen>
<para>你也可以将工作拷贝更新到旧的修订版本（Subversion没有CVS的<quote>sticky</quote>文件的概念；见<xref
- linkend="svn-ap-a"/>）：</para>
+ linkend="svn.forcvs"/>）：</para>
<screen>
$ svn update -r30
@@ -3261,18 +3558,19 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 2 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-9-sect-2">
+ <!-- ================================================================= -->
+ <sect1 id="svn.ref.svnadmin">
<title><command>svnadmin</command></title>
<para><command>svnadmin</command>是一个用来监控和修改Subversion版本库的管理工具，详情请见<xref
- linkend="svn-ch-5-sect-3.1.2"/>。</para>
+ linkend="svn.reposadmin.maint.tk.svnadmin"/>。</para>
<para>因为<command>svnadmin</command>直接访问版本库（因此只可以在存放版本库的机器上使用），它通过路径访问版本库，而不是URL。
</para>
- <sect2 id="svn-ch-9-sect-2.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.ref.svnadmin.sw">
<title><command>svnadmin</command> Switches</title>
<variablelist>
@@ -3355,15 +3653,34 @@
<para>不显示通常的过程—只显示错误。</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>--use-post-commit-hook</option></term>
+ <listitem>
+ <para>When loading a dump file, run the repository's
+ post-commit hook after finalizing each newly loaded
+ revision.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--use-pre-commit-hook</option></term>
+ <listitem>
+ <para>When loading a dump file, run the repository's
+ pre-commit hook before finalizing each newly loaded
+ revision. If the hook fails, abort the commit and
+ terminate the load process.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect2>
- <!-- ================================================================= -->
- <sect2 id="svn-ch-9-sect-2.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.ref.svnadmin.c">
<title><command>svnadmin</command> Subcommands</title>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-create">
+ <refentry id="svn.ref.svnadmin.c.create">
<refnamediv>
<refname>svnadmin create</refname>
<refpurpose>创建一个新的空的版本库。</refpurpose>
@@ -3376,7 +3693,7 @@
<title>描述</title>
<para>在提供的路径上创建一个新的空的版本库，如果提供的目录不存在，它会为你创建。<footnote><para>记住<command>svnadmin</command>只工作在本地<emphasis>路径</emphasis>，而不是<emphasis>URL</emphasis>。
- </para></footnote></para>
+ </para></footnote>对于Subversion 1.2，<command>svnadmin</command>缺省使用<literal>fsfs</literal>文件系统后端创建版本库。</para>
</refsect1>
<refsect1>
@@ -3409,8 +3726,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-deltify">
+ <refentry id="svn.ref.svnadmin.c.deltify">
<refnamediv>
<refname>svnadmin deltify</refname>
<refpurpose>修订版本范围的路径的增量变化。</refpurpose>
@@ -3439,8 +3755,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-dump">
+ <refentry id="svn.ref.svnadmin.c.dump">
<refnamediv>
<refname>svnadmin dump</refname>
<refpurpose>将文件系统的内容转储到标准输出。</refpurpose>
@@ -3452,12 +3767,46 @@
<refsect1>
<title>描述</title>
- <para>使用<quote>dumpfile</quote>可移植格式将文件系统的内容转储到标准输出，将反馈发送到标准错误，导出的修订版本从<replaceable>LOWER</replaceable>到<replaceable>UPPER</replaceable>。如果没有提供修订版本，会导出所有的修订版本树，如果只提供<replaceable>LOWER</replaceable>，导出一个修订版本树，通常的用法见<xref linkend="svn-ch-5-sect-3.5"/>。
+ <para>使用<quote>dumpfile</quote>可移植格式将文件系统的内容转储到标准输出，将反馈发送到标准错误，导出的修订版本从<replaceable>LOWER</replaceable>到<replaceable>UPPER</replaceable>。如果没有提供修订版本，会导出所有的修订版本树，如果只提供<replaceable>LOWER</replaceable>，导出一个修订版本树，通常的用法见<xref linkend="svn.reposadmin.maint.migrate"/>。
</para>
- <para>如果Subversion的转储文件很大，你可以使用<option>--deltas</option>来减小<command>svnadmin</command>创建的导出文件的大小。通过这个选项，就不会写出每次修订版本的内容，<command>svnadmin dump</command>只会写出版本之间的区别。然而，创建增量导出文件的坏处—对CPU的要求更高，<command>svndumpfilter</command>不可以对这个文件操作，而且非增量的转储文件可以更好的压缩。
- </para>
-
+ <para>By default, the Subversion dumpfile stream contains a
+ single revision (the first revision in the requested
+ revision range) in which every file and directory in the
+ repository in that revision is presented as if that whole
+ tree was added at once, followed by other revisions (the
+ remainder of the revisions in the requested range) which
+ contain only the files and directories which were modified
+ in those revisions. For a modified file, the complete
+ fulltext representation of its contents, as well as all of
+ its properties, are presented in the dumpfile; for a
+ directory, all of its properties are presented.</para>
+
+ <para>There are a pair of useful options which modify the
+ dumpfile generator's behavior. The first is the
+ <option>--incremental</option> option, which simply causes
+ that first revision in the dumpfile stream to contain only
+ the files and directories modified in that revision,
+ instead of being presented as the addition of a new tree,
+ and in exactly the same way that every other revision in
+ the dumpfile is presented. This is useful for generating
+ a dumpfile that is to be loaded into another repository
+ which already has the files and directories that exist in
+ the original repository.</para>
+
+ <para>The second useful option is <option>--deltas</option>.
+ This switch causes <command>svnadmin dump</command> to,
+ instead of emitting fulltext representations of file
+ contents and property lists, emit only deltas of those
+ items against their previous versions. This reduces (in
+ some cases, drastically) the size of the dumpfile that
+ <command>svnadmin dump</command> creates. There are, however,
+ disadvantages to using this option—deltified
+ dumpfiles are more CPU intensive to create, cannot be
+ operated on by <command>svndumpfilter</command>, and tend
+ not to compress as well as their non-deltified counterparts
+ when using third-party tools like <command>gzip</command>
+ and <command>bzip2</command>.</para>
</refsect1>
<refsect1>
<title>选项</title>
@@ -3500,8 +3849,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-help">
+ <refentry id="svn.ref.svnadmin.c.help">
<refnamediv>
<refname>svnadmin help</refname>
</refnamediv>
@@ -3525,8 +3873,7 @@
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-hotcopy">
+ <refentry id="svn.ref.svnadmin.c.hotcopy">
<refnamediv>
<refname>svnadmin hotcopy</refname>
<refpurpose>制作一个版本库的热备份。</refpurpose>
@@ -3554,8 +3901,7 @@
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-list-dblogs">
+ <refentry id="svn.ref.svnadmin.c.list-dblogs">
<refnamediv>
<refname>svnadmin list-dblogs</refname> <refpurpose>询问Berkeley DB在给定的Subversion版本库有哪些日志文件存在（只有在版本库使用<literal>bdb</literal>作为后端时使用）。
</refpurpose>
@@ -3567,15 +3913,14 @@
<refsect1>
<title>描述</title>
- <para>Berkeley DB创建了记录所有版本库修改的日志，允许我们在面对大灾难时恢复。除非你开启了<literal>DB_LOGS_AUTOREMOVE</literal>，否则日志文件会累积，尽管大多数是不再使用可以从磁盘删除得到空间。详情见<xref
- linkend="svn-ch-5-sect-3.3"/>。
+ <para>Berkeley DB创建了记录所有版本库修改的日志，允许我们在面对大灾难时恢复。除非你开启了<literal>DB_LOG_AUTOREMOVE</literal>，否则日志文件会累积，尽管大多数是不再使用可以从磁盘删除得到空间。详情见<xref
+ linkend="svn.reposadmin.maint.diskspace"/>。
</para>
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-list-unused-dblogs">
+ <refentry id="svn.ref.svnadmin.c.list-unused-dblogs">
<refnamediv>
<refname>svnadmin list-unused-dblogs</refname>
<refpurpose>询问Berkeley DB哪些日志文件可以安全的删除（只有在版本库使用<literal>bdb</literal>作为后端时使用）。
@@ -3589,8 +3934,8 @@
<title>描述</title>
<para>
- Berkeley DB创建了记录所有版本库修改的日志，允许我们在面对大灾难时恢复。除非你开启了<literal>DB_LOGS_AUTOREMOVE</literal>，否则日志文件会累积，尽管大多数是不再使用，可以从磁盘删除得到空间。详情见<xref
- linkend="svn-ch-5-sect-3.3"/>。</para>
+ Berkeley DB创建了记录所有版本库修改的日志，允许我们在面对大灾难时恢复。除非你开启了<literal>DB_LOG_AUTOREMOVE</literal>，否则日志文件会累积，尽管大多数是不再使用，可以从磁盘删除得到空间。详情见<xref
+ linkend="svn.reposadmin.maint.diskspace"/>。</para>
</refsect1>
<refsect1>
@@ -3611,8 +3956,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-load">
+ <refentry id="svn.ref.svnadmin.c.load">
<refnamediv>
<refname>svnadmin load</refname> <refpurpose>从标准输出读取<quote>转储文件</quote>格式流。
</refpurpose>
@@ -3635,6 +3979,8 @@
--quiet (-q)
--ignore-uuid
--force-uuid
+--use-pre-commit-hook
+--use-post-commit-hook
--parent-dir
</screen>
</refsect1>
@@ -3667,8 +4013,48 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-lstxns">
+ <refentry id="svn.ref.svnadmin.c.lslocks">
+ <refnamediv>
+ <refname>svnadmin lslocks</refname>
+ <refpurpose>Print descriptions of all locks.</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Synopsis</title>
+ <programlisting>svnadmin lslocks REPOS_PATH</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+
+ <para>Print descriptions of all locks in a repository.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Switches</title>
+
+ <para>None</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Example</title>
+
+
+ <para>This lists the one locked file in the repository at
+ <filename>/svn/repos</filename></para>
+
+ <screen>
+$ svnadmin lslocks /svn/repos
+Path: /tree.jpg
+UUID Token: opaquelocktoken:ab00ddf0-6afb-0310-9cd0-dda813329753
+Owner: harry
+Created: 2005-07-08 17:27:36 -0500 (Fri, 08 Jul 2005)
+Expires:
+Comment (1 line):
+Rework the uppermost branches on the bald cypress in the foreground.
+</screen>
+ </refsect1>
+ </refentry>
+
+ <refentry id="svn.ref.svnadmin.c.lstxns">
<refnamediv>
<refname>svnadmin lstxns</refname>
<refpurpose>打印所有未提交的事物名称。</refpurpose>
@@ -3680,7 +4066,7 @@
<refsect1>
<title>描述</title>
- <para>打印所有未提交的事物名称。关于未提交事物是怎样创建和如何使用的信息见<xref linkend="svn-ch-5-sect-3.2"/>。
+ <para>打印所有未提交的事物名称。关于未提交事物是怎样创建和如何使用的信息见<xref linkend="svn.reposadmin.maint.cleanup"/>。
</para>
</refsect1>
@@ -3698,12 +4084,10 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-recover">
+ <refentry id="svn.ref.svnadmin.c.recover">
<refnamediv>
<refname>svnadmin recover</refname>
- <refpurpose>将版本库数据库恢复到稳定状态（只有在版本库使用<literal>bdb</literal>作为后端时使用）。
- </refpurpose>
+ <refpurpose>将版本库数据库恢复到稳定状态（只有在版本库使用<literal>bdb</literal>作为后端时使用），此外，如果<filename>repos/conf/passwd</filename>不存在，它会创建一个默认的密码文件。</refpurpose>
</refnamediv>
<refsect1>
<title>概要</title>
@@ -3763,9 +4147,46 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
+<refentry id="svn.ref.svnadmin.c.rmlocks">
+ <refnamediv>
+ <refname>svnadmin rmlocks</refname>
+ <refpurpose>Unconditionally remove one or more locks from a
+ repository.</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Synopsis</title>
+ <programlisting>svnadmin rmlocks REPOS_PATH LOCKED_PATH...</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+
+ <para>Remove lock from each <replaceable>LOCKED_PATH</replaceable>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Switches</title>
+
+ <para>None</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Example</title>
+
+ <para>This deletes the locks on
+ <filename>tree.jpg</filename> and
+ <filename>house.jpg</filename> in the repository at
+ <filename>/svn/repos</filename></para>
+
+ <screen>
+$ svnadmin rmlocks /svn/repos tree.jpg house.jpg
+Removed lock on '/tree.jpg.
+Removed lock on '/house.jpg.
+</screen>
+ </refsect1>
+ </refentry>
+
- <refentry id="svn-ch-9-sect-2.2-re-rmtxns">
+ <refentry id="svn.ref.svnadmin.c.rmtxns">
<refnamediv>
<refname>svnadmin rmtxns</refname>
<refpurpose>从版本库删除事物。</refpurpose>
@@ -3778,7 +4199,7 @@
<title>描述</title>
<para>删除版本库突出的事物，更多细节在<xref
- linkend="svn-ch-5-sect-3.2"/>。
+ linkend="svn.reposadmin.maint.cleanup"/>。
</para>
</refsect1>
@@ -3812,8 +4233,7 @@
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-setlog">
+ <refentry id="svn.ref.svnadmin.c.setlog">
<refnamediv>
<refname>svnadmin setlog</refname>
<refpurpose>设置某个修订版本的日志信息。</refpurpose>
@@ -3860,8 +4280,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-2.2-re-verify">
+ <refentry id="svn.ref.svnadmin.c.verify">
<refnamediv>
<refname>svnadmin verify</refname>
<refpurpose>验证版本库保存的数据。</refpurpose>
@@ -3895,9 +4314,9 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 3 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-9-sect-3">
+ <!-- ================================================================= -->
+ <sect1 id="svn.ref.svnlook">
<title><command>svnlook</command></title>
<para><command>svnlook</command>是检验Subversion版本库不同方面的命令行工具，它不会对版本库有任何修改—它只是用来<quote>看</quote>。<command>svnlook</command>通常被版本库钩子使用，但是版本库管理也会发现它在诊断目的上也非常有用。
@@ -3908,7 +4327,8 @@
<para>如果没有指定修订版本或事物，<command>svnlook</command>缺省的是版本库最年轻的（最新的）修订版本。
</para>
- <sect2 id="svn-ch-9-sect-3.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.ref.svnlook.sw">
<title><command>svnlook</command>选项</title>
<para><command>svnlook</command>的选项是全局的，就像<command>svn</command>和<command>svnadmin</command>；然而，大多数选项只会应用到一个子命令，因为<command>svnlook</command>的功能是（有意的）限制在一定范围的。
@@ -3932,6 +4352,19 @@
</varlistentry>
<varlistentry>
+ <term><option>--revprop</option></term>
+ <listitem>
+ <para>Operates on a revision property instead of a
+ Subversion property specific to a file or directory.
+ This switch requires that you also pass a revision
+ with the <option>--revision</option>
+ (<option>-r</option>) switch. See <xref
+ linkend="svn.reposadmin.basics.revprops"/> for more details on
+ unversioned properties.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--transaction</option>
(<option>-t</option>)</term>
<listitem>
@@ -3950,11 +4383,11 @@
</sect2>
- <!-- ================================================================= -->
- <sect2 id="svn-ch-9-sect-3.2">
+ <!-- =============================================================== -->
+ <sect2 id="svn.ref.svnlook.c">
<title><command>svnlook</command></title>
- <refentry id="svn-ch-9-sect-3.2-re-author">
+ <refentry id="svn.ref.svnlook.c.author">
<refnamediv>
<refname>svnlook author</refname>
<refpurpose>打印作者。</refpurpose>
@@ -3992,8 +4425,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-cat">
+ <refentry id="svn.ref.svnlook.c.cat">
<refnamediv>
<refname>svnlook cat</refname>
<refpurpose>打印一个文件的内容。</refpurpose>
@@ -4043,8 +4475,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-changed">
+ <refentry id="svn.ref.svnlook.c.changed">
<refnamediv>
<refname>svnlook changed</refname>
<refpurpose>打印修改的路径。</refpurpose>
@@ -4056,11 +4487,53 @@
<refsect1>
<title>描述</title>
- <para>打印在特定修订版本或事物修改的路径，也是在第一列使用<quote>svn
- update样式的</quote>状态字符：<literal>A</literal>表示添加，<literal>D</literal>表示删除，<literal>U</literal>表示更新（修改）。
- </para>
+ <para>打印在特定修订版本或事物修改的路径，也是在前两列使用<quote>svn
+ update样式的</quote>状态字符：
+ </para>
+ <variablelist>
+
+ <varlistentry>
+ <term>'<literal>A </literal>'</term>
+ <listitem>
+ <para>Item added to repository.</para>
+ </listitem>
+ </varlistentry>
- </refsect1>
+ <varlistentry>
+ <term>'<literal>D </literal>'</term>
+ <listitem>
+ <para>Item deleted from repository.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>'<literal>U </literal>'</term>
+ <listitem>
+ <para>File contents changed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>'<literal>_U</literal>'</term>
+ <listitem>
+ <para>Properties of item changed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>'<literal>UU</literal>'</term>
+ <listitem>
+ <para>File contents and properties changed.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>Files and directories can be distinguished, as directory
+ paths are displayed with a trailing '<literal>/</literal>'
+ character.</para>
+
+ </refsect1>
<refsect1>
<title>选项</title>
@@ -4083,13 +4556,16 @@
A trunk/vendors/deli/chips.txt
A trunk/vendors/deli/sandwich.txt
A trunk/vendors/deli/pickle.txt
+U trunk/vendors/baker/bagel.txt
+_U trunk/vendors/baker/croissant.txt
+UU trunk/vendors/baker/pretzel.txt
+D trunk/vendors/baker/baguette.txt
</screen>
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-date">
+ <refentry id="svn.ref.svnlook.c.date">
<refnamediv>
<refname>svnlook date</refname>
<refpurpose>打印时间戳。</refpurpose>
@@ -4126,8 +4602,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-diff">
+ <refentry id="svn.ref.svnlook.c.diff">
<refnamediv>
<refname>svnlook diff</refname>
<refpurpose>打印修改的文件和属性的区别。</refpurpose>
@@ -4149,6 +4624,7 @@
<screen>
--revision (-r)
--transaction (-t)
+--no-diff-added
--no-diff-deleted
</screen>
</refsect1>
@@ -4189,8 +4665,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-dirs-changed">
+ <refentry id="svn.ref.svnlook.c.dirs-changed">
<refnamediv>
<refname>svnlook dirs-changed</refname>
<refpurpose>打印本身修改的目录。</refpurpose>
@@ -4228,8 +4703,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-help">
+ <refentry id="svn.ref.svnlook.c.help">
<refnamediv>
<refname>svnlook help</refname>
</refnamediv>
@@ -4251,8 +4725,7 @@
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-history">
+ <refentry id="svn.ref.svnlook.c.history">
<refnamediv>
<refname>svnlook history</refname>
<refpurpose>打印版本库（如果没有路径，则是根目录）某一个路径的历史。</refpurpose>
@@ -4307,8 +4780,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-info">
+ <refentry id="svn.ref.svnlook.c.info">
<refnamediv>
<refname>svnlook info</refname>
<refpurpose>打印作者、时间戳、日志信息大小和日志信息。
@@ -4349,8 +4821,53 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-log">
+
+ <refentry id="svn.ref.svnlook.c.lock">
+ <refnamediv>
+ <refname>svnlook lock</refname>
+ <refpurpose>If a lock exists on a path in the repository,
+ describe it.</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Synopsis</title>
+ <programlisting>svnlook lock REPOS_PATH PATH_IN_REPOS</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+
+ <para>Print all information available for the lock at
+ <replaceable>PATH_IN_REPOS</replaceable>. If
+ <replaceable>PATH_IN_REPOS</replaceable> is not locked,
+ print nothing.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Switches</title>
+
+ <para>None</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <para>This describes the lock on the file
+ <filename>tree.jpg</filename>.</para>
+
+ <screen>
+$ svnlook lock /svn/repos tree.jpg
+UUID Token: opaquelocktoken:ab00ddf0-6afb-0310-9cd0-dda813329753
+Owner: harry
+Created: 2005-07-08 17:27:36 -0500 (Fri, 08 Jul 2005)
+Expires:
+Comment (1 line):
+Rework the uppermost branches on the bald cypress in the foreground.
+</screen>
+
+ </refsect1>
+ </refentry>
+
+
+ <refentry id="svn.ref.svnlook.c.log">
<refnamediv>
<refname>svnlook log</refname>
<refpurpose>打印日志信息。</refpurpose>
@@ -4387,8 +4904,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-propget">
+ <refentry id="svn.ref.svnlook.c.propget">
<refnamediv>
<refname>svnlook propget</refname>
<refpurpose>打印版本库中一个路径一个属性的原始值。</refpurpose>
@@ -4415,6 +4931,7 @@
<screen>
--revision (-r)
--transaction (-t)
+--revprop
</screen>
</refsect1>
@@ -4431,8 +4948,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-proplist">
+ <refentry id="svn.ref.svnlook.c.proplist">
<refnamediv>
<refname>svnlook proplist</refname>
<refpurpose>打印版本化的文件和目录的属性名称和值。</refpurpose>
@@ -4461,6 +4977,7 @@
--revision (-r)
--transaction (-t)
--verbose (-v)
+--revprop
</screen>
</refsect1>
@@ -4488,8 +5005,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-tree">
+ <refentry id="svn.ref.svnlook.c.tree">
<refnamediv>
<refname>svnlook tree</refname>
<refpurpose>打印树。</refpurpose>
@@ -4535,8 +5051,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-uuid">
+ <refentry id="svn.ref.svnlook.c.uuid">
<refnamediv>
<refname>svnlook uuid</refname>
<refpurpose>打印版本库的<literal>UUID</literal>。</refpurpose>
@@ -4548,7 +5063,7 @@
<refsect1>
<title>描述</title>
- <para>打印版本库的<literal>UUID</literal>，UUID是版本库的<emphasis>U</emphasis>niversal <emphasis>U</emphasis>nique
+ <para>打印版本库的<literal>UUID</literal>，UUID是版本库的<emphasis>u</emphasis>niversal <emphasis>u</emphasis>nique
<emphasis>ID</emphasis>entifier（全局唯一标示），Subversion客户端可以使用这个标示区分不同的版本库。
</para>
</refsect1>
@@ -4564,8 +5079,7 @@
</refsect1>
</refentry>
- <!-- ================================================================= -->
- <refentry id="svn-ch-9-sect-3.2-re-youngest">
+ <refentry id="svn.ref.svnlook.c.youngest">
<refnamediv>
<refname>svnlook youngest</refname>
<refpurpose>打印最年轻的修订版本号。</refpurpose>
@@ -4597,19 +5111,20 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 4 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-9-sect-4">
+ <!-- ================================================================= -->
+ <sect1 id="svn.ref.svnserve">
<title><command>svnserve</command></title>
<para><command>svnserve</command>允许Subversion版本库使用<literal>svn</literal>网络协议，你可以作为独立服务器进程运行svnserve，或者是使用其它进程，如<command>inetd</command>、<command>xinetd</command>或<command>sshd</command>为你启动进程。
</para>
- <para>一旦客户端已经选择了一个版本库来传递它的URL，<command>svnserve</command>会读取版本库目录的<filename>conf/svnserve.conf</filename>文件，来检测版本库特定的设置，如使用哪个认证数据库和应用怎样的授权策略。关于<filename>svnserve.conf</filename>文件的详情见<xref linkend="svn-ch-6-sect-3"/>。
+ <para>一旦客户端已经选择了一个版本库来传递它的URL，<command>svnserve</command>会读取版本库目录的<filename>conf/svnserve.conf</filename>文件，来检测版本库特定的设置，如使用哪个认证数据库和应用怎样的授权策略。关于<filename>svnserve.conf</filename>文件的详情见<xref linkend="svn.serverconfig.svnserve"/>。
</para>
- <sect2 id="svn-ch-9-sect-4.1">
+ <!-- =============================================================== -->
+ <sect2 id="svn.ref.svnserve.sw">
<title><command>svnserve</command>选项</title>
<para>不象前面描述的例子，<command>svnserve</command>没有子命令—<command>svnserve</command>完全通过选项控制。
@@ -4692,7 +5207,7 @@
<varlistentry>
<term><option>--tunnel-user NAME</option></term>
<listitem>
- <para>与<option>--tunnel</option>选项结合使用；告诉svnserve假定NAME就是认证用户，而不是svnserve进程的UID用户，当希望多个用户通过SSH共享同一个系统帐户，但是维护各自的提交标示符时非常有用。
+ <para>与<option>--tunnel</option>选项结合使用；告诉svnserve假定<replaceable>NAME</replaceable>就是认证用户，而不是svnserve进程的UID用户，当希望多个用户通过SSH共享同一个系统帐户，但是维护各自的提交标示符时非常有用。
</para>
</listitem>
</varlistentry>
@@ -4720,34 +5235,34 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 5 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-9-sect-5">
+ <!-- ================================================================= -->
+ <sect1 id="svn.ref.svnversion">
<title><command>svnversion</command></title>
- <refentry id="svn-ch-9-sect-5.1">
+ <refentry id="svn.ref.svnversion.re">
<refnamediv>
<refname>svnversion</refname>
<refpurpose>总结工作拷贝的本地修订版本。</refpurpose>
</refnamediv>
- <refsect1 id="svn-ch-9-sect-5.1.1">
+ <refsect1 id="svn.ref.svnversion.re.syn">
<title>概要</title>
<programlisting>svnversion [OPTIONS] WC_PATH [TRAIL_URL]</programlisting>
</refsect1>
- <refsect1 id="svn-ch-9-sect-5.1.2">
+ <refsect1 id="svn.ref.svnversion.re.desc">
<title>描述</title>
<para><command>svnversion</command>是用来总结工作拷贝修订版本混合的程序，结果修订版本号或范围会写到标准输出。
</para>
- <para>如果提供TRAIL_URL，URL的尾端部分用来监测是否WC_PATH本身已经跳转（监测WC_PATH的跳转不需要依赖TRAIL_URL）。</para>
+ <para>如果提供<replaceable>TRAIL_URL</replaceable>，URL的尾端部分用来监测是否<replaceable>WC_PATH</replaceable>本身已经跳转（监测<replaceable>WC_PATH</replaceable>的跳转不需要依赖<replaceable>TRAIL_URL</replaceable>）。</para>
</refsect1>
- <refsect1 id="svn-ch-9-sect-5.1.3">
+ <refsect1 id="svn.ref.svnversion.re.sw">
<title>选项</title>
<para>像<command>svnserve</command>，<command>svnversion</command>没有子命令，只有选项。
@@ -4788,7 +5303,7 @@
</variablelist>
</refsect1>
- <refsect1 id="svn-ch-9-sect-5.1.4">
+ <refsect1 id="svn.ref.svnversion.re.examples">
<title>例子</title>
<para>如果工作拷贝都是一样的修订版本（例如，在更新后那一刻），会打印修订版本：
@@ -4835,13 +5350,13 @@
</sect1>
<!-- ================================================================= -->
- <!-- ======================== SECTION 6 ============================== -->
<!-- ================================================================= -->
- <sect1 id="svn-ch-9-sect-6">
+ <!-- ================================================================= -->
+ <sect1 id="svn.ref.mod_dav_svn">
<title><command>mod_dav_svn</command></title>
- <refentry id="svn-ch-9-sect-6.1">
+ <refentry id="svn.ref.mod_dav_svn.conf">
<refnamediv>
<refname><literal>mod_dav_svn</literal> Configuration
@@ -4850,16 +5365,16 @@
</refnamediv>
- <refsect1 id="svn-ch-9-sect-6.1.1">
+ <refsect1 id="svn.ref.mod_dav_svn.conf.desc">
<title>描述</title>
<para>这个小节主要描述了Subversion Apache配置的每个指示，关于Apache配置Subversion的更多信息见<xref
- linkend="svn-ch-6-sect-4"/>。
+ linkend="svn.serverconfig.httpd"/>。
</para>
</refsect1>
- <refsect1 id="svn-ch-9-sect-6.1.2">
+ <refsect1 id="svn.ref.mod_dav_svn.conf.directives">
<title>Directives</title>
<variablelist>
@@ -4875,6 +5390,25 @@
</varlistentry>
<varlistentry>
+ <term><literal>SVNAutoversioning On</literal></term>
+ <listitem>
+
+ <para>This directive allows write requests from WebDAV
+ clients to result in automatic commits. A generic log
+ message is auto-generated and attached to each
+ revision. If you enable Autoversioning, you'll likely
+ want to set <literal>ModMimeUsePathInfo On</literal>
+ so that <literal>mod_mime</literal> can set
+ <literal>svn:mime-type</literal> to the correct
+ mime-type automatically (as best as
+ <literal>mod_mime</literal> is able to, of course).
+ For more information, see <xref
+ linkend="svn.webdav"/></para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>SVNPath</literal></term>
<listitem>
@@ -4928,7 +5462,7 @@
<listitem>
<para>控制开启和关闭路径为基础的授权，更多细节见<xref
- linkend="svn-ch-6-sect-4.4.3"/>。
+ linkend="svn.serverconfig.httpd.authz.pathauthzoff"/>。
</para>
</listitem>
Modified: trunk/src/zh/book/copyright.xml
==============================================================================
--- trunk/src/zh/book/copyright.xml (original)
+++ trunk/src/zh/book/copyright.xml Wed Jan 25 01:01:34 2006
@@ -1,10 +1,10 @@
-<appendix id="svn-copyright">
+<appendix id="svn.copyright">
<title>版权</title>
<simplesect>
<programlisting>
-Copyright (c) 2002-2004
+Copyright (c) 2002-2005
Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato.
该软件已经在Creative Commons Attribution License中登记。
Modified: trunk/src/zh/book/foreword.xml
==============================================================================
--- trunk/src/zh/book/foreword.xml (original)
+++ trunk/src/zh/book/foreword.xml Wed Jan 25 01:01:34 2006
@@ -3,7 +3,7 @@
the best solution for now, even though there's also a real preface in
ch00.xml. -->
-<preface id="svn-foreword">
+<preface id="svn.foreword">
<title>前言</title>
<simplesect>
More information about the svnbook-dev
mailing list