SubGit中文手册:获取一个远程subversion库镜像

一. 介绍
SubGit是用java语言编写的。SubGit是一种subversion与git代码库之间双向同步工具。如何在本地subversion版本库上安装SubGit请参考下片文章。本片文章主要说明使用SubGit创建git镜像远程subversion版本库。

通常情况下，subversion版本库是通过网络访问的，如http(s)、svn、svn+SSH、本地文件系统。相应地，用户请求是通过apache web服务器、svnserve守护进程、sshd守护进程调用svnserve进程。如下图所示：

用户使用subgit来创建和配置git版本库，与远程的subversion版本库保持同步。每一个git库镜像一个subversion项目，也有可能是多个项目包含在单个subversion版本库中。代码的更改推到git版本库上，会立马转换到subversion项目上。反之亦然，subversion项目的提交也会反映到相对应的git版本库上。

或者，可以在subversion端启用代码库的pre-revprop-change钩子功能，这将使subgit使用单一的subversion用户账号，不过这种修改是不需要的，所以即使subversion版本库，你没有shell访问通过subgit来镜像。下图显示了典型的subgit建立，通过subgit来创建一个远程subversion版本库的git镜像：

在镜像初始化阶段，subgit转换现有的subversion修订本到一个新创建的git仓库上。还有一种方法，跳过镜像，一次性的从subversion导入到git。

小结：
1. subgit创建git仓库，镜像于远端的subversion版本库
2. subgit可一次性从subversion导入到git
3. 不需要直接shell访问subversion版本库
4. subgit授予用户选择是否使用git还是subversion，提供平滑迁移路径
5. subgit使用java语言实现的，因此需要java1.5版本及以上

二. subgit特性
主要好处有：
1. 强大的转换和初始的导入性能(与git-svn对比 参见http://www.ttlsa.com/html/1864.html)
2. 没有限制(与git-svn相反)
3. 不需要shell访问subversion版本库

subgit包含强大的转换引擎，将转化：
1. 合并跟踪信息和历史
2. 非线性git提交历史到subversion
3. 子项目、标签和分支
4. svn:ignore 和 .gitignore忽略定义
5. svn:eol-style 和 .gitattributes特殊属性
6. 符号链接
7. 提交作者和日期
8. 文件和目录重命名

三. 镜像配置介绍
要同步subversion和git版本库，subgit映射一个系统的实体到另一个。一个git仓库总是映射到subversion版本库上的一个单一的项目。也有可能是有一种到多种项目的subversion版本库。git库包含subgit以下的信息和映射配置：
1. subversion项目在subversion版本库的位置
2. subversion项目的分支和标签映射到git的分支和标签引用
3. subversion用户映射到git提交者
上面的映射是在转换和同步开始之前的静态配置。所有的映射和其他信息存储在GIT_REPOS/subgit目录下。下面的各界将介绍这些映射的详细信息。

3.1 subversion项目位置
subversion版本库可能包含一个或多个项目。每个项目推荐使用subversion版本库布局，如trunk、branches、tags子目录

并不是非得要trunk、branches和tags文件夹，但是这些文件夹的作用是很重要的。
下图所示每个项目映射到一个空的git库
Single Project Repository Mapping

SubGit configuration file (single project mapping)

Multiple Projects Repository Mapping

SubGit configuration file (two projects mapping)

3.2 Branches 和 Tags映射
对于每一个项目映射到一个git库，branches和tags映射到git库中相对应引用。subgit区分subversion项目下的branches或tags文件夹：
1. trunk folder
2. 专用文件夹中的branches文件夹
3. 专用文件夹中的shelves文件夹
4. 专用文件夹中的tags文件夹

shelves是一种特殊的branches，给subgit使用的用于在subversion版本库中代表git匿名的branches。
每个文件夹都映射到git库中的引用。对于trunk文件夹，映射是一对一的。其他文件夹使用通配符映射。
每当项目使用标准的文件夹名称如trunk、branches、tags，subgit将会自动检测和配置该项目的映射。否则，配置将需要手工更改，包括适当的路径和引用名称。
Default Branches and Tags Mapping：

SubGit configuration file (default branches and tags mapping):

SubGit configuration file (non-standard folders names)：

Project and Branches Mapping：

3.3 作者映射
默认情况下，如果没有明确的作者映射，转换将使用下面的规则：
1. Subversion “svn_user_name” is translated to “svn_user_name <>” in Git
2. Git “Author Name <email@domain.com>” is translated to “Author Name” in Subversion

另外的默认规则，可以通过subgit配置来明确作者的映射。默认情况下，作者映射存储在一个单独的文本文件GIT_REPOS/subgit/authors.txt

GIT_REPOS/subgit/authors.txt file：

可更变authors.txt存储位置：
SubGit configuration file defines authors.txt location：

作者的映射文件内容可能会随时改变，新的映射可能立即生效。

四. 一次性从subversion导入到git
有时候没必要保持git库与subversion版本库的同步，而直接一次性解决。subgit提供快捷的import命令，让用户在命令行中指定所有必要的选项，从而自动化批量导入。

在大多数情况下，预先存在的subversion认证存储就足够了，唯一要指定subversion项目的URL参数：

五. 创建subversion版本库的git镜像
5.1 安装阶段
subversion版本库转换到git库和启用双向同步，其中一个必须使用subgit来创建和配置git库。创建镜像包括三个阶段：创建库、配置调整和安装。
Mirror Creation Stages：

在配置阶段，subgit创建git库，默认的镜像配置存入其中，然后用户有机会调整生成配置。在安装阶段，subgit执行现有的subversion修订转换到git提交，同时启动同步。

5.2 运行subgit配置
运行subgit配置命令使subgit创建空的git库，并将其链接到subversion项目。
在运行配置命令时，用户需要指定subversion项目URL，将从最低版本开始同步。

在配置阶段，subgit不会与subversion版本库建立连接，但是生成配置文件信息在进行安装时很有必要的。如下所示：

5.3 调整配置：介绍
subgit配置命令创建空的git库，写入默认配置，并映射到GIT_REPOS/subgit/config文件。调整默认生成的配置，然后再进入安装阶段。在特定的用户必须提供凭证或指定哪里可以找到他们，以便于subgit访问subversion版本库。 默认生成的配置文件如下所示：

subgit/config可以指定相对的或绝对的路径。相对路径被视为相对git库跟目录。

5.4 调整配置：提供作者映射
将subversion用户映射到git作者写入到conf/authors.txt文件。如下所示：

或者指定以存在的作者映射文件：

指定作者映射文件是core.authorsFile可选值。路径相对于subversion版本库跟(如conf/authors.txt对应于SVN_REPOS/conf/authors.txt)或指定绝对路径。

为遗失的email指定默认域：

email是git作者信息的一部分， 在没有找到作者映射或没有提供email下，subgit将使用core.defaultDomain值来生成作者email.

5.5 调整配置：路径编码

git存储路径作为一个字节序列，不指定编码，通常是以本地文件系统编码。在subversion字符串路径转化到git库时，使用git.pathEncoding选项来指定编码。大多数系统都被配置成utf-8编码的。推荐配置此参数。

5.6 调整配置：branches映射

svn.url选项值指定项目位置。被用作跟URL来相对映射路径。

有四种分支必须映射，每个代表自身的选项：trunk、branches、tags、shelves。每个选项建立对应的SVN_PATH到GIT_REFERENCE特定种类实体，trunk映射语法如下：

svn.trunk选项允许指定单个SVN_PATH:GIT_REFERENCE映射作为它的值。SVN_PATH路径相对于svn.url项目位置，GIT_REFERENCE是一个git参考，如refs/heads/master。映射的含义是在subversion项目中所做的更改将转换到git提交GIT_REFERENCE。在GIT_REFERENCE提交将转换更改到SVN_PATH。branches、tags、shelves映射语法如下：

这些选项允许指定多个映射，每个映射可以定义多对多的关系。映射可以是一对一或多对多的。换句话说，当使用通配符*将映射到两端。每个选项必须至少包含一个多对多的映射(其中带*通配符)，例如：

上面的映射实例，subversion的所有branches目录映射到git的refs/heads命名空间，此外，release_branches/b1分支映射到git分支引用refs/releases/b1。

在指定映射时格外小心，在同步启动时，不可能再调整的。通过subgit只有branches和tags所包含的映射将导入并保持同步。

5.7 调整配置：凭证
为了在subversion版本库中创建新的修订版，subgit需要subversion服务器的授权认证。subgit用户可以提供多套凭证(用户名/密码对)。在创建新的修订时，subgit可以选择用户名来授权。

GIT_REPOS/subgit/passwd文件：subgit来读取用户名/密码对。密码是明文的。最好限制这个文件的访问权限。

在subgit配置文件中指定GIT_REPOS/subgit/passwd文件路径：

SubGit配置文件：指定明确的ssh和ssl客户端凭证

本地subversion凭证缓存：为了使subgit可以从本地subversion凭证缓存中读取凭证，需要设置auth.useDefaultSubversionConfigurationDirectory选择为true，同时需要指定缓存文件路径。

5.8 凭证和subversion pre-revprop-change钩子
为创建新的subversion版本，subgit需要subversion服务器验证授权。为了做到这些，subgit遵循下面的算法：
1. git的提交作者需和subversion作者匹配
2. 所有的源凭证配置迭代查询作者凭证
3. 在凭证匹配情况下，subgit使用它们授权
4. 在凭证不匹配情况下，subgit使用任何可用的
5. 一旦提交新的修订版，subgit设置该作者的svn:author修订属性

最安全配置subgit凭证的方式是提供单一的凭证，要么明确指定subgit/passwd文件，要么指定本部subversion配置文件路径。然而，使用subversion版本属性功能需要启用subversion版本库的pre-revprop-change钩子。添加一个空的钩子脚本，退出代码为0来启动修订属性：

Linux and OS X系统:

Windows系统:

5.9 调整配置：其他选项

设置subversion版本的svn.minimalRevision值来指定从哪里开始转换。修订比指定的老蒋不会转换，将不存在于git库。通过该选项来限制修订范围可以减少转换时间。

5.10 运行subgit安装
运行subgit安装命令使subgit开始从subversion转换到git，同时启动之前产生的配置命令synchronization.install。

最初的转换需要一段时间，在这段时间git库是可读的，但是，推是禁用的。
subgit安装命令启动同步安装钩子到git库。已存在的git pre-receive和post-receive钩子将保留并正常执行。
Repository after install command is completed：

一旦安装命令报告成功终止，git用户就可以推代码到git库。新的提交将被转换到新的subversion版本库修订，反之亦然，新的subversion修订将被转换到新的git提交。

5.11 后台执行转换
一旦安装完成后，subgit启动后台进程，定期拉取subversion版本库。每当新的修订被发现，将转换为git提交。这样，git库在大部分时间保持最新。这个后台进程是可选的，可以被killed。当后台进程没有运行时，新的subversion修订将通过git用户推pre-receive钩子来处理。除非在配置文件中禁用，用户推将重启启动后台转换进程。
配置GIT_REPOS/subgit/config文件来定义subgit进程：

设置daemon.idleTimeout选项为0，后台转换进程可能会被禁用。在这种情况下，推完成，转换进程立即退出：

强制转换未完成的subversion修订，可以通过下面命令：

或者调用从远程工作树no-op推：

上面的命令将尝试删除不存在的远程分支和强制subgit同步git与subversion库。

优雅关闭后台进程命令：

5.12 推荐的git客户端配置
git用户将从服务器上克隆git库到本地。有一些配置选项建议添加到.git/config配置文件中。虽说不是必须的，但是会带来更好的用户体验。
Fetch SubGit mapping information:
[remote “origin”]

refs/notes/commmits包含每个提交到git的映射信息。有了这些记录，git log命令将展示映射信息和提交信息：

Fetch all tags:

–tags选项将强制git获取所有的标签，即使从当前分支不可取得。

六. 更改subgit配置
6.1 Writing Hooks
为了使subversion和git同步，subgit安装钩子到git库。这些钩子是：
1. Git pre-receive hook
2. Git post-receive hook
这些钩子对于subgit正常工作至关重要的，用户不应该修改或删除这些钩子脚本。如有必要，上面这些钩子应该放置到user-*在适当的时候。subgit安装命令在意以存在的钩子，并自动将其内容写入到相应的user-*脚本中。
下表显示了标准的钩子脚本文件和subgit安装后的文件名对应关系。subgit不会影响钩子的参数和返回代码规则。未在表中列出的钩子不会被subgit使用，标准的文件名称不会改变。

在windows系统下，subversion钩子文件是以.cmd或.bat作为扩展名的。

6.2 应用配置更改
subgit安装到库后，subgit配置可以更改。一些改变将会立即生效，其他需要安装subgit，重建要执行的命令，使应用更改。
更改立即生效场景:
1. 修改作者映射文件subgit/authors.txt
2. 修改密码凭证文件subgit/passwd
3. 修改或创建user-*钩子脚本

执行’subgit install’命令后更改才生效场景：
1. 修改subgit/config文件的core.authorsFile选项
2. 修改subgit/config文件的svn.fetchInterval选项
3. 修改subgit/config文件的[auth]部分

subgit install命令将验证subgit/config所做的更改，并将这些更改应用。 如果需要的话，重新启动后台转换进程。

其他配置更改：尤其是更改subgit/config文件的branches映射，最简单的方法是安装标准配置阶段重新安装subgit。在以安装subgit下，更改branches不可能映射到git库。停止后台转换进程，在git库上执行subgit uninstall命令。

七. 卸载subgit
运行subgit uninstall命令禁止同步或卸载subgit。
运行uninstall未带选项将删除subgit钩子，从而停止转换：

在运行subgit uninstall带上–purge选项，将完全删除subgit。–purge将删除：
1. subgit二进制和日志文件
2. subgit元数据

八. 注册subgit
注不注册随你所好。

九. 转换局限性
subversion和git版本控制系统解决了同样了问题，那就是为什么subversion和git代码库同步是可能的。然而，subversion和git实现不同，因此两者有些实体是没法转换的。
下面的实体没法从subversion转换到git：
1. 任意用户定义的属性
2. 版本属性
3. svn:externals属性
4. 空目录
5. 锁文件
6. cherry-pick合并跟踪信息
7. subversion基于路径验证

下面的实体没法从git转换到subversion：
1. git子模块
2. git笔记
3. 不相关的文件属性

subgit未来版本或许将删除上述限制。

十. 备份
subgit2.0版本不提供集成的备份解决方案。标准的git工具可以用来备份库。

备份git库：
首先，禁止git推，然后禁止subgit同步:

uninstall命令将等待未完成的转换，然后关闭转换后台进程。执行jps命令确保它没有在运行，检查是否有SubGitDaemon java进程。然后，备份一切数据，重新安装subgit、启动同步和git推：

十一. 系统需求
subgit可以运行在大部分系统上，要求如下：
1. Windows XP or newer, Linux or OS X
2. Oracle Java 1.5 or newer
3. 至少256MB*K可用内存，K是subversion版本库的数量

subgit2.0钩子脚本使用本地预编译的可执行文件，因此每个推启动JVM没有开销。有些系统可能无法执行预编译二进制，subgit将回落到基于java的钩子。在这种情况下，内存需要以32Mb*N倍数增加,N是推的最大并发数。

可用内存包括物理内存和swap分区，在subgit高峰时，最好能多分配写内存。

十二. 安装subgit工具
下载相关系统平台安装包：http://subgit.com/download/