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

  • A+
所属分类:SVN

一. 介绍
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.bhlaab.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://www.bhlaab.com/647/download/

如需转载请注明出处:SubGit中文手册:获取一个远程subversion库镜像?http://www.bhlaab.com/html/1906.html

微信公众号
扫一扫关注运维生存时间公众号,获取最新技术文章~

发表评论


目前评论:1   其中:访客  0   博主  0   引用   1

    来自外部的引用: 1

    • SVN版本库迁移到Git工具SubGit