SVN用户使用指南.doc

SVN用户使用指南Version 1.0文档变更记录文件状态： 草稿 正式发布 当前版本：V1.0作 者：谭斌审 核 人：发布日期：修订号修改内容描述修改人修改日期备注目 录1. 引言11.1. 目的11.2. 范围12. SVN基础知识12.1. SVN简介12.2. SVN特性12.3. SVN的架构33. SVN的基本应用43.1. 客户端的安装43.2. 版本库浏览 Repo-browser63.3. 版本库的基本操作83.3.1. Add file（folder）添加文件(文件夹)83.3.2. commit 提交93.3.3. Show log 查看日志93.3.4. Export 导出113.3.5. Revision graph 版本树显示123.3.6. Check out 检出133.3.7. Refresh 刷新133.3.8. Delete 删除143.3.9. Rename 对目录或文件进行改名143.3.10. Copy to working copy 把当前目录拷贝到本地153.3.11. Copy to 拷贝到163.4. 客户端操作173.4.1. 客户端的基本操作173.4.2. 常用功能介绍203.4.3. 分支与合并234. SVN API254.1. 使用API254.2. URL和路径需求274.3. 使用C和C+以外的语言274.4. 代码样例284.4.1. 使用版本库层284.4.2. 使用Python处理版本库层354.4.3. 一个Python状态爬虫404.5. 参考资料451. 引言1.1. 目的为了对配置管理工具(Subversion,以下简称为SVN)应用过程提供指导，编制此指南.1.2. 范围本规范适应于北京高伟达软件技术有限公司内部使用2. SVN基础知识2.1. SVN简介SVN 是一具开源的版本控制系统，SVN 将文件存放在中心版本库里，这个版本库很像一个普通的文件服务器，不同的是，它可以记录每一次文件的修改情况。这样我们就可以籍此将数据回复到以前的版本，并可以查看的更改细节。也就是说，一旦一个文件被传到SVN 上面，那么不管对它进行什么操作，SVN 都会有清晰的记录，即使它在N 天前被删除了，也可以被找回来。所以，许多人将版本控制系统当作一种神奇的“时间机器”。2.2. SVN特性Ø 版本化目录SVN 实现的“虚拟”版本化文件系统可以跟踪目录树的变更。也就是说，在SVN 中，文件和目录都是版本化的。Ø 真实的版本历史由于实现了文件和目录的版本化，SVN 可以记录如文件拷贝和改名这些常见操作带来的版本变更，即在SVN 中，对文件或目录都可以进行增加、拷贝和操作，并有版本历史记录。Ø 原子提交一系列相关的更改，要么全部提交到版本库，要么一个也不提交，这样用户就可以将相关的更改组成一个逻辑整体，防止出现部分修改需另一部分未修改的情况提交到版本库中。Ø 可选的网络层SVN 在版本库访问的实现上具有较高的抽象程度，利于人们实现新的网络访问机制。SVN 可以作为一个扩展模块嵌入到Apache 之中，这种方式在稳定性和交互性方面有很大的优势，可以直接使用服务器的成熟技术-认证、授权和传输压缩等。此外，SVN 自身也实现了一个轻型的、可独立运行的服务器软件。这个服务器使用了一个特定的协议，这个协议可以轻松用SSH 封装。我们目前选用的是SVN 自身的服务器，即Svnserver 方式，本文主要是对Svnserver 方式的使用方法介绍。Ø 一致的数据操作SVN 用一个二进制差算法描述文件和变化，对于文件（可读）和二进行制（不可读）文件其操作方式是一致的。这两种类型的文件压缩存储在版本库中，而差异信息则在网络上双向传递。Ø 高效的分支和标签操作在 SVN 中，分支与标签操作的开销与工程的大小无关，SVN 的分支和标签操作是一种类似于硬链接的机制拷贝整个工程。因而这些操作通常只会花费很少且相对固定的时间。Ø 可修改性SVN 没有历史负担，它以一系列优质的共享C 程序库的方式实现，具有定义良好的API。2.3. SVN的架构3. SVN的基本应用3.1. 客户端的安装点击Yes,重启电脑，完成安装。3.2. 版本库浏览 Repo-browser完成安装之后,点击鼠标右键,会出现下图,这是SVN的基本功能,下面一一介绍.点击Repo-browser之后，会出现下面的小对话框：在里面输入你要键接的版本库:输入方法为：https:/服务器IP:端口号/所在版本库名称，如PQA的配置库为：https:/10.0.5.8：8443/PQA（记得svn 是小写字母的），点“OK”进入登录界面。如果以前有登录过，SVN 会自动记录登录历史。登录界面如下：输入用户名和密码即可进入所在的版本库。3.3. 版本库的基本操作3.3.1. Add file（folder）添加文件(文件夹)用此命令可以向服务器端目录添加一个本地的文件或文件夹。3.3.2. commit 提交使用commit命令可以将add的文件添加到服务器3.3.3. Show log 查看日志点击此按扭，会显示当前目录下的所有文件和目录日志的信息。会跳出下面的对话框：3.3.4. Export 导出用此命令，指定路径，便可导出一个干净的目录树，所谓“干净的”就是导出的文件不受SVN 的版本控制。默认的是导出当前版本的目录内容，当然也可以指定你想导出的版,如图所示:在Export directory中选择本地的路径.3.3.5. Revision graph 版本树显示 它可以把对此目录所做的所有操作以图的形式显示出来，并可以记录每一步都进行了什么操作，相当于“Show log”的一个图解，如下图所示：3.3.6. Check out 检出用此命令可以从服务器导出选中的目录到本地工作拷贝（本机），它和Export 的区别在于，检出的文件受版本控制，如下图所示：3.3.7. Refresh 刷新刷新服务器端目录。3.3.8. Delete 删除对目录或文件都可以进行删除操作，删除后版本号增加，可以通过“show log”找出已经删除的文件,并且可以看到文件夹变成:注意：文件只有在自己的工作副本中删除了，必须执行commit，文件才算是真正的删除了。3.3.9. Rename 对目录或文件进行改名如果要对文件进行改名，要在服务器端对文件或文件夹用Rename 命令，改完后在本地工作拷贝的上级目录执行“Commit”即可。可以在本地用右键，使用TSVN 的菜单改名，提交后效果一样。3.3.10. Copy to working copy 把当前目录拷贝到本地本地工作拷贝必须是已经受版本控制的文件夹，执行此命令后,如：把“01 参考资料”复制到本地工作拷贝的“PQA”中，就会出现下图，绿色的对号表示此目录是从服务器上“Checkout”出来的受版本控制的本地工作拷贝，蓝色的加号表示此文件预添加到服务器上。这时，在此目录空白处或选中“01参考资料”文件夹，右键执行“SVN Commit”命令如下图所示：“01参考资料”便会成功提交到服务器上“PQA”的目录下面。3.3.11. Copy to 拷贝到用此命令可以在当前版本库中建立分支（标签/基线），SVN 允许并行的维护文件和目录的分支，各个分支间互相联系，也可以从一个分支复制修改到另一个分支，最终，可以让本地工作拷贝反映到不同的分支上，所以在日常的工作中，可以“混合和比较”不同的开发线。3.4. 客户端操作3.4.1. 客户端的基本操作在本地工作拷贝空白处点击右键会出现如下图所示，下面对此菜单中常用的功能做详细的介绍.工作拷贝就是执行“checkout”命令从服务器端检出到本地的一个目录，是个人的一个私有工作区，在此目录下，可以任意的编辑文件，如果是源代码文件，可以像平常一样编译。比如，我们对过程记录中会议记录中一个文件的日期做修改，被编辑后的文件和它的上一级目录都会显示为：这时可以对此文件执行 SVN Commit 提交操作，那么编辑的内容便会提交到服务器上，以便大家共享你的工作成果。这时对改后的版本点击右键，执行“Show log”后，可以显示版本日志，如果想看到本次的改动和原始的版本有何差别，那么选中当前版本记录，右键执行“show changes”如下图所示：这时它就会显示本次是哪些动作导致了版本的变化，红色部分新增加的内容,它以标注的方式显示：还要补充说明的是，在SVN 上，有三种权限：读、读写、无权限。如果想对你的工作拷贝进行编辑，那么你必须有在这个目录下读写的权限，如果在服务器端此目录下面你无权限或只有读的权限，那么即使在本地拷贝做了修改，也不能提交到服务器上，也就是说，每个有读权限的人可以看查版本库目录下的内容（无权限的不能查看），但只能对自己被赋予读写权限的目录做修改。这就保护了你的工作目录不会被别的人随意改动。3.4.2. 常用功能介绍3.4.2.1. Revert 返回上一级如果你对文件做了修改之后，还未进行提交，可是文档的标记已经为红色的叹号，而这时你又发现变错了，想把文档返回到原来的状态，这时你可以执行Revert 操作，便可使文档回到原来的状态，因为你没有执行提交操作，这时服务器上版本库版本号不会增加。3.4.2.2. Update to revision 返回到版本如果是你已经执行了提交操作，这时可以用Update to revision 命令，在跳出的对话框中选择你想返回到的版本，那么你的本地工作拷贝便会回到你所选的版本的状态。“Save revision to”也可以把原来版本进行存档。强调一点的是，你的本地工作拷贝可以返回到原来的版本，可是服务器上只会记录你对它进行最后一次提交的版本，所以服务器端版本不会变化，如果你想把服务器端的文档内容也换为原来的状态，可以用旧版本文件覆盖新版本文件，然后提交。3.4.2.3. Import 导入导入是一种批量向服务器上添加文件的方法，如果你想把本地的文件或文件夹添加到服务器上的某个目录下面，那么在本地的目录中，在空白处右键TortoisrSVNImport，会跳出下面的对话框：点“OK”后就可以把本地的文件或文件夹导入到服务器端所选目录下面。3.4.2.4. SVN Update 更新用此命令可以更新你的工作拷贝，因为每个人都有自己的工作拷贝，在你对项目目录进行操作的同时，项目组其他人员也在进行编辑并提交的动作，版本库内容随着项目人员的每一次提交做着不同的变化，所以在每次编辑操作之前，都要对本地工作拷贝执行Update 的操作，以保证本地工作拷贝与服务器项目版本库内容保持一致。3.4.2.5. Resolved 冲突已解决当两个人同时编辑一个文件，一个人先提交后，另一个人再进行提交的时候就会出现冲突，这时会弹出冲突对话框，如下图所示:你可以对出现的冲突的文件进行编辑，选定你最终想要的文档。这就是“Merge”合并操作。在出现冲突以及应用分支时会经常用到合并的功能。合并完毕后，执行 Resolved，则新的版本就被生成了。3.4.2.6. Switch 切换把你的工作拷贝切换到另个的URL（服务器目录），服务器端目录有所变化，所存储的文件位置发生了变化，那么对你的工作拷贝进行编辑后就会出现提交不上去的情况，这时就要执行Switch 操作，使你的工作拷贝切换到服务器端对应的目录下面，即可再进行提交。Switch 操作只限于版本库内的切换。3.4.2.7. Relocate 重新定位它和Switch 的功能是一样的，不同的是，它实现的是版本库与版本库之间的切换。当服务器地址或版本库名称发生变化时，可以用些命令来更新你的工作拷贝。3.4.2.8. Create（Apply） patch 创建应用补丁如果你对这个文件没有修改的权限，但是迫于形势，你又必须对这个文件进行修改，这时你就可以用Create patch 创建补丁，然后把你创建的补丁发给对此目录有写权限的工作人员，他执行Apply patch后，你所做的修改就会被提交到服务器上。3.4.3. 分支与合并3.4.3.1. 从项目主分支下载项目初始源码到开发分支操作步骤:1. 在trunk目录新建一个项目名称为Astx;2. 在Astx项目中新建两个模块分别为module1和module2,分别为新建一个名 test.txt的文件;3. 选择Astx项目名称，右击选择branch/tag;4. 请注意 From WC at URL必须是项目Astx的根路径，To URL：在这里选择branch 存放的路径，通常的路径为:http:/localhost/svn/Astx/branches/astx_dev_tb; 注:Branches为分支的存放路径，astx_dev_tb为分支的名称5. 在branches 目录右击update，就可以看到刚才的astx_dev_tb分支；3.4.3.2. 把分支(astx_dev_tb)的的修改合并到项目主分支操作步骤:1. 选择项目主分支右击TortoiseSVN选择 merge,选择 Reintegrate a branch；2. 点击Next,在URL to merge from 的地址栏中选择astx_dev_tb分支的路径； 注意Working copy是项目主分支的路径;3. 点击NEXT,在Merge depth 下拉框中选择 “working copy”,点击Merge, 将分支的修改合并到主干上；4. 在项目主分支右击commit，整个的过程才算完成！5. 如果要退回前一个版本，选择项目主分支右击TortoiseSVN选择Revert,将取消本 次合并的内容.3.4.3.3. 两个不同分支的修改合并到项目主分支3.4.3.3.1. 修改同一个文件的不同行操作步骤:1. 基于项目主分支创建两个不同的分支分别为:astx_dev_john,astx_dev_harry(创建分支的方法，请参照1.1);注: john和harry 为同一个项目创建自己的工作副本，工作是并行的.2. john和harry修改同一个文件text.txt的不同行,john先保存修改到版本库(具体 的合并的步骤，请参照1.2),最后别忘了commit!3. 当harry提交修改的时候，版本库提示文件text.txt在他上次更新之后已经更改了, 如果john修改的内容不和harry的冲突，一旦把所有的修改集成到一起，就可以把工作拷贝保存到版本库,最后别忘了commit! 3.4.3.3.2. 修改同一个文件的同一行操作步骤:1. 基于项目主分支创建两个不同的分支分别为:astx_dev_john,astx_dev_harry;注: john和harry 为同一个项目创建自己的工作副本，工作是并行的.2. john和harry修改同一个文件text.txt的同一行,john先保存修改到版本库(具体的合并的步骤，请参照1.2);3. 当harry提交修改的时候，版本库提示文件text.txt冲突，这时只能够人工去选择一组修改，并把所有的修改集成到一起，就可以把工作拷贝保存到版本库,记得做完之后一定要commit!4. SVN API4.1. 使用API使用Subversion库API开发应用看起来相当的直接，所有的公共头文件放在源文件的subversion/include目录，从源代码编译和安装Subversion本身，需要这些头文件拷贝到系统位置。这些头文件包括了所有用户和Subversion库可以访问的功能和类型。Subversion开发者社区仔细的确保所有的公共API有完好的文档直接引用头文件的文档。你首先应该注意Subversion的数据类型和方法是命名空间保护的，每一个公共Subversion对象名以svn_开头，然后紧跟一个这个对象定义（如wc、client和fs等等）所在的库的简短编码，然后是一个下划线（_）和后面的对象名称。半公开的方法（库使用，但是但库之外代码不可以使用并且只可以在库自己的目录看到）与这个命名模式不同，并不是库代码之后紧跟一个下划线，他们是用两个下划线（_）。给定源文件的私有方法没有特殊前缀，使用static声明。当然，一个编译器不会关心命名习惯，只是用来区分给定方法或数据类型的应用范围。关于Subversion的API编程的另一个好的资源是hacking指南，可以在http:/subversion.tigris.org/hacking.html找到，这个文档包含了有用的信息，同时满足Subversion本身的开发者和将Subversion作为第三方库的开发者。Apache 可移值运行库伴随Subversion自己的数据类型，你会看到许多apr开头的数据类型引用来自Apache可移植运行库（APR）的对象。APR是Apache可移植运行库，源自为了服务器代码的多平台性，尝试将不同的操作系统特定字节与操作系统无关代码隔离。结果就提供了一个基础API的库，只有一些适度区别或者是广泛的来自各个操作系统。Apache HTTP服务器很明显是APR库的第一个用户，Subversion开发者立刻发现了使用APR库的价值。意味着Subversion没有操作系统特定的代码，也意味着Subversion客户端可以在Server存在的平台编译和运行。当前这个列表包括，各种类型的Unix、Win32、OS/2和Mac OS X。除了提供了跨平台一致的系统调用， APR给Subversion对多种数据类型有快速的访问，如动态数组和哈希表。Subversion在代码中广泛使用这些类型，但是Subversion的API原型中最常见的APR类型是apr_pool_tAPR内存池，Subversion使用内部缓冲池用来进行内存分配（除非外部库在API传递参数时需要一个不同的内存管理模式），而且一个人如果针对Subversion的API编码不需要做同样的事情，他们可以在需要时给API提供缓冲池，这意味着Subversion的API使用者也必须链接到APR，必须调用apr_initialize()来初始化APR子系统，而且在使用Subversion API时必须创建和管理池，通常是使用svn_pool_create()、svn_pool_clear()和svn_pool_destroy()。使用内存池编程几乎每一个使用过C语言的开发者曾经感叹令人畏缩的内存管理，分配足够的内存，并且追踪内存的分配，在不需要时释放内存这个任务会非常复杂。当然，如果没有正确地做到这一点会导致程序毁掉自己，或者更加严重一点，把电脑搞瘫。另一方面高级语言使开发者完全摆脱了内存管理，53Java和Python之类的语言使用垃圾收集原理，在需要的时候分配对象内存，在不使用时进行清理。APR提供了一种叫做池基础的中等的内存管理方法，允许开发者以一种低分辨率的方式控制内存每块（或池“pool”）的内存，而不是每个对象。不是使用malloc()和其他按照对象分配内存的方式，你要求APR从内存创建一段内存池，当你结束使用在池中创建的对象，你销毁池，可以有效地取消其中的对象消耗的内存。通过池，你不需要跟踪每个对象的内存释放，你的程序只需要跟踪这些对象，将对象分配到池中，而池的生命周期（池的创建和删除之间的时间）满足所有对象的需要。4.2. URL和路径需求因为分布式版本控制操作是Subversion存在的重点，有意义来关注一下国际化（i18n）支持。毕竟，当“分布式”或许意味着“横跨办公室”，它也意味着“横跨全球”。为了更容易一点，Subversion的所有公共接口只接受路径参数,这些参数是传统的，使用UTF-8编码。这意味着，举个例子，任何新的使用libsvn_client接口客户端库，在把这些参数传递给Subversion库前，需要首先将路径从本地代码转化为UTF-8代码，然后将Subversion传递回来的路径转换为本地代码，很幸运，Subversion提供了一组任何程序可以使用的转化方法（见subversion/include/svn_utf.h）。同样，Subversion的API需要所有的URL参数是正确的URI编码，所以，我们不会传递file:/home/username/My File.txt作为My File.txt的URL，而要传递file:/home/username/My%20File.txt。再次，Subversion提供了一些你可以使用的助手方法svn_path_uri_encode()和svn_path_uri_decode()，分别用来URI的编码和解码。4.3. 使用C和C+以外的语言除C语言以外，如果你对使用其他语言结合Subversion库感兴趣如Python脚本或是Java应用Subversion通过简单包裹生成器（SWIG）提供了最初的支持。Subversion的SWIG绑定位于subversion/bindings/swig，并且慢慢的走向成熟进入可用状态。这个绑定允许你直接调用Subversion的API方法，使用包裹器会把脚本数据类型转化为Subversion需要的C语言库类型。非常不幸，Subversion的语言绑定缺乏对核心Subversion模块的关注，但是，花了很多力气处理创建针对Python、Perl和Ruby的功能绑定，在一定程度上，在这些接口上的工作量可以在其他语言的SWIG（包括C#、Guile、Java、MzScheme、OCaml、PHP、Tcl等等）接口上得到重用。然而，为了完成复杂的API，一些SWIG接口仍然需要额外的编程工作，关于SWIG本身的更多信息可以看项目的网站http:/www.swig.org/。Subversion也有Java的语言绑定，JavaJL绑定（位于Subversion源目录树的subversion/bindings/java）不是基于SWIG的，而是javah和手写JNI的混合，JavaHL几乎覆盖Subversion客户端的API，目标是作为Java基础的Subversion客户端和集成IDE的实现。Subversion的语言绑定缺乏Subversion核心模块的关注，但是通常可以作为一个产品信赖。大量脚本、应用、Subversion的GUI客户端和其他第三方工具现在已经成功地运用了Subversion语言绑定来完成Subversion的集成。这里使用其它语言的方法来与Subversion交互没有任何意义：Subversion开发社区没有提供其他的绑定，你可以在Subversion项目链接页里（http:/subversion.tigris.org/links.html）找到其他绑定的链接，但是有一些流行的绑定我觉得应该特别留意。首先是Python的流行绑定，Barry Scott的PySVN（http:/pysvn.tigris.org/）。PySVN鼓吹它们提供了更多Python样式的接口，而不像Subversion自己的Python绑定的C样式接口。对于希望寻求Subversion纯Java实现的人，可以看看SVNKit（4.4. 代码样例4.4.1. 使用版本库层使用版本库层中包含了一段C代码（C编写）描述了我们讨论的概念，它使用了版本库和文件系统接口（可以通过方法名svn_repos_和svn_fs_分辨）创建了一个添加目录的修订版本。你可以看到APR库的使用，为了内存分配而传递，这些代码也揭开了一些关于Subversion错误处理的晦涩事实所有的Subversion错误必须需要明确的处理以防止内存泄露（在某些情况下，应用失败）。/* Convert a Subversion error into a simple boolean error code. * * NOTE: Subversion errors must be cleared (using svn_error_clear() * because they are allocated from the global pool, else memory * leaking occurs. */#define INT_ERR(expr) do svn_error_t *_temperr = (expr); if (_temperr) svn_error_clear(_temperr); return 1; return 0; while (0)/* Create a new directory at the path NEW_DIRECTORY in the Subversion * repository located at REPOS_PATH. Perform all memory allocation in * POOL. This function will create a new revision for the addition of * NEW_DIRECTORY. Return zero if the operation completes * successfully, non-zero otherwise. */static intmake_new_directory(const char *repos_path, const char *new_directory, apr_pool_t *pool) svn_error_t *err; svn_repos_t *repos; svn_fs_t *fs; svn_revnum_t youngest_rev; svn_fs_txn_t *txn; svn_fs_root_t *txn_root; const char *conflict_str; /* Open the repository located at REPOS_PATH. */ INT_ERR(svn_repos_open(&repos, repos_path, pool); /* Get a pointer to the filesystem object that is stored in REPOS. */ fs = svn_repos_fs(repos); /* Ask the filesystem to tell us the youngest revision that * currently exists. */ INT_ERR(svn_fs_youngest_rev(&youngest_rev, fs, pool); /* Begin a new transaction that is based on YOUNGEST_REV. We are * less likely to have our later commit rejected as conflicting if we * always try to make our changes against a copy of the latest snapshot * of the filesystem tree. */ INT_ERR(svn_fs_begin_txn(&txn, fs, youngest_rev, pool); /* Now that we have started a new Subversion transaction, get a root * object that represents that transaction. */ INT_ERR(svn_fs_txn_root(&txn_root, txn, pool); /* Create our new directory under the transaction root, at the path * NEW_DIRECTORY. */ INT_ERR(svn_fs_make_dir(txn_root, new_directory, pool); /* Commit the transaction, creating a new revision of the filesystem * which includes our added directory path. */ err = svn_repos_fs_commit_txn(&conflict_str, repos, &youngest_rev, txn, pool); if (! err) /* No error? Excellent! Print a brief report of our success. */ printf("Directory '%s' was successfully added as new revision " "'%ld'.n", new_directory, youngest_rev); 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 * of the filesystem that we tried to modify). Print an error * message. */ printf("A conflict occurred at path '%s' while attempting " "to add directory '%s' to the repository at '%s'.n", conflict_str, new_directory, repos_path); else /* Some other error has occurred. Print an error message. */ printf("An error occurred while attempting to add directory '%s' " "to the repository at '%s'.n", new_directory, repos_path); INT_ERR(err); 4.4.2. 使用Python处理版本库层同样的C程序需要处理APR内存池系统，但是Python自己处理内存，Subversion的Python绑定也遵循这种习惯。在C语言中，为表示路径和条目的hash需要处理自定义的数据类型（例如APR提供的库），但是Python有hash（叫做“dictionaries”），并且是内置数据类型，而且还提供了一系列操作这些类型的函数，所以SWIG（通过Subversion的语言绑定层的自定义帮助）要小心的将这些自定义数据类型映射到目标语言的数据类型，这为目标语言的用户提供了一个更加直观的接口。#!/usr/bin/python"""Crawl a repository, printing versioned object path names."""import sysimport os.pathimport svn.fs, svn.core, svn.reposdef crawl_filesystem_dir(root, directory): """Recursively crawl DIRECTORY under ROOT in the filesystem, and return a list of all the paths at or below DIRECTORY.""" # Print the name of this path. print directory + "/" # Get the directory entries for DIRECTORY. entries = svn.fs.svn_fs_dir_entries(root, directory) # Loop over the entries. name