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子目录
/project /trunk # 项目主线 /branches # 包含项目功能和版本分支，从trunk或其他branches复制过来的 /tags # 包含项目标签，trunk和branches的快照
并不是非得要trunk、branches和tags文件夹，但是这些文件夹的作用是很重要的。
下图所示每个项目映射到一个空的git库
Single Project Repository Mapping
SubGit configuration file (single project mapping)
[svn] # URL that points to a project root # (may be the same as Subversion repository root) url = http://host/svn/repos
Multiple Projects Repository Mapping
SubGit configuration file (two projects mapping)
/var/git/project1.git/subgit/config
[svn]
# project location within Subversion repository
url = http://host/svn/repos/project1
...
/var/git/project2.git/subgit/config
[svn]
# project location within Subversion repository
url = http://host/svn/repos/project23.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):
[svn] url = http://host/svn/repos/project1 # branches and tags mapping in form of # branchKind=Subversion-Path-Pattern:Git-Reference-Pattern trunk = trunk:refs/heads/master branches = branches/*:refs/heads/* shelves = shelves/*:refs/shelves/* tags = tags/*:refs/tags/*
SubGit configuration file (non-standard folders names)：
[svn] url = http://host/svn/repos/project2 # branches and tags mapping in form of # branchKind=Subversion-Path-Pattern:Git-Reference-Pattern trunk = main:refs/heads/master branches = versions/*:refs/heads/* shelves = shelves/*:refs/shelves/* tags = stamps/*:refs/tags/*
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：
svn_user_name = Git Name <name@email.com>
可更变authors.txt存储位置：
SubGit configuration file defines authors.txt location：
[core] ... # location of the authors mapping file authorsFile = subgit/authors.txt ...
作者的映射文件内容可能会随时改变，新的映射可能立即生效。
四. 一次性从subversion导入到git
有时候没必要保持git库与subversion版本库的同步，而直接一次性解决。subgit提供快捷的import命令，让用户在命令行中指定所有必要的选项，从而自动化批量导入。
# subgit help import
info: Import SVN or Git repository.
usage: subgit import [--svn-url URL] [--default-domain DOMAIN] [--minimal-revision REV] [--authors-file FILE] [--trunk PATH] [--branches PATH] [--tags PATH] [--username SVN_USERNAME] [--password SVN_PASSWORD] [--non-interactive] [--trust-server-cert] [--private-key SVN_PRIVATE_KEY_PATH] [--private-key-passphrase SVN_PRIVATE_KEY_PASSPHRASE] REPOS_PATH
Import existing Subversion project at URL into Git repository at REPOS_PATH.
When Git repository at REPOS_PATH does not exist it will be created.
Upon import completion optionally one may get rid of SubGit-specific files
by running 'subgit uninstall --purge REPOS_PATH' or start continuous synchronization
by running 'subgit install REPOS_PATH'.
Valid options:
--svn-url URL : specify URL of remote Subversion repository
--default-domain DOMAIN : domain to be used to generate Git committer name by SVN committer name
if there's no corresponding rule in authors file
--minimal-revision REV : specify Subversion revision REV to start translation from;
revisions less than REV would not be translated
--authors-file FILE : authors mapping file used to map Subversion committers names
to Git committers names
-T [--trunk] PATH : path to a directory that plays the role of SVN trunk,
relative to project root specified by --svn-url
-b [--branches] PATH : path to a directory that plays the role of SVN branches directory,
relative to project root specified by --svn-url
-t [--tags] PATH : path to a directory that plays the role of SVN tags directory,
relative to project root specified by --svn-url
--username SVN_USERNAME : username to use to access Subversion repository;
if no username is specified, SubGit may prompt for it later
--password SVN_PASSWORD : password to use to access Subversion repository;
if no password is specified, SubGit may prompt for it later
--non-interactive : do no interactive prompting
--trust-server-cert : accept unknown SSL server certificates without
prompting (but only with '--non-interactive')
--private-key : path to private key file to use to access Subversion repository;
if no path is specified, SubGit may prompt for it later
--private-key-passphrase: passphrase for private key file to use to access Subversion repository;
if no passphrase is specified, SubGit may ask for it later在大多数情况下，预先存在的subversion认证存储就足够了，唯一要指定subversion项目的URL参数：
# subgit import --non-interactive --svn-url http://svn.svnkit.com/repos/sqljet sqljet.git
SubGit version 2.0.0-EAP ('Patrick') build #2552
This is an EAP build, which you may not like to use in production environment.
Translating Subversion revisions to Git commits...
Subversion revisions translated: 1292.
Total time: 579 seconds.
IMPORT SUCCESSFUL五. 创建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 configure --svn-url http://svn.svnkit.com/repos/sqljet sqljet.git
SubGit version 2.0.0 ('Patrick') build #2552
Configuring writable Git mirror of remote Subversion repository:
Subversion repository URL : http://svn.svnkit.com/repos/sqljet
Git repository location : sqljet.git
CONFIGURATION SUCCESSFUL在配置阶段，subgit不会与subversion版本库建立连接，但是生成配置文件信息在进行安装时很有必要的。如下所示：
git_repository/
branches
hooks
logs
objects
refs
subgit/
lib/ # SubGit binaries
logs/ # SubGit logs
authors.txt # default authors mapping (empty)
config # SubGit configuration file
passwd # Password credentials to access Subversion repository
format # Information on SubGit version
config # Git configuration file
HEAD5.3 调整配置：介绍
subgit配置命令创建空的git库，写入默认配置，并映射到GIT_REPOS/subgit/config文件。调整默认生成的配置，然后再进入安装阶段。在特定的用户必须提供凭证或指定哪里可以找到他们，以便于subgit访问subversion版本库。 默认生成的配置文件如下所示：
[core]
authorsFile = subgit/authors.txt
pathEncoding = UTF-8
defaultDomain = tmatesoft.com
[svn]
url = http://svn.svnkit.com/repos/sqljet
trunk = trunk:refs/heads/master
branches = branches/*:refs/heads/*
tags = tags/*:refs/tags/*
shelves = shelves/*:refs/shelves/*
fetchInterval = 60
connectTimeout = 30
readTimeout = 60
auth = default
[auth "default"]
passwords = subgit/passwd
useDefaultSubversionConfigurationDirectory = false
subversionConfigurationDirectory = /home/user/subversionsubgit/config可以指定相对的或绝对的路径。相对路径被视为相对git库跟目录。
5.4 调整配置：提供作者映射
将subversion用户映射到git作者写入到conf/authors.txt文件。如下所示：
conf/authors.txt: semen = Semen Vadishev <vadishev@tmatesoft.com> dmitry = Dmitry Pavlenko <pavlenko@tmatesoft.com>
或者指定以存在的作者映射文件：
[core]
...
authorsFile = /var/git/company-authors-mapping.txt指定作者映射文件是core.authorsFile可选值。路径相对于subversion版本库跟(如conf/authors.txt对应于SVN_REPOS/conf/authors.txt)或指定绝对路径。
为遗失的email指定默认域：
[core]
...
defaultDomain = company.comemail是git作者信息的一部分， 在没有找到作者映射或没有提供email下，subgit将使用core.defaultDomain值来生成作者email.
5.5 调整配置：路径编码
[core]
...
pathEncoding = UTF-8git存储路径作为一个字节序列，不指定编码，通常是以本地文件系统编码。在subversion字符串路径转化到git库时，使用git.pathEncoding选项来指定编码。大多数系统都被配置成utf-8编码的。推荐配置此参数。
5.6 调整配置：branches映射
[svn]
...
url = http://host/svn/repossvn.url选项值指定项目位置。被用作跟URL来相对映射路径。
[svn]
...
trunk = trunk:refs/heads/master
branches = branches/*:refs/heads/*
tags = tags/*:refs/tags/*
shelves = shelves/*:refs/shelves/*有四种分支必须映射，每个代表自身的选项：trunk、branches、tags、shelves。每个选项建立对应的SVN_PATH到GIT_REFERENCE特定种类实体，trunk映射语法如下：
trunk = SVN_PATH:GIT_REFERENCE
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映射语法如下：
branches = SVN_PATH[/*]:GIT_REFERENCE[/*][;MAPPING]
这些选项允许指定多个映射，每个映射可以定义多对多的关系。映射可以是一对一或多对多的。换句话说，当使用通配符*将映射到两端。每个选项必须至少包含一个多对多的映射(其中带*通配符)，例如：
branches = branches/*:refs/heads/*;release_branhces/b1:refs/release/b1
上面的映射实例，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来读取用户名/密码对。密码是明文的。最好限制这个文件的访问权限。
username password username1 secret ... usernameN anothersecret
在subgit配置文件中指定GIT_REPOS/subgit/passwd文件路径：
[auth "default"]
...
passwords = subgit/passwdSubGit配置文件：指定明确的ssh和ssl客户端凭证
[auth "default"]
...
sshKeyFile = /home/user/ssh-private-key.openssh
sshKeyFilePassphrase = secret
sslClientCertFile = /home/user/ssl-client-cert.p12
sslClientCertPassphrase = secret本地subversion凭证缓存：为了使subgit可以从本地subversion凭证缓存中读取凭证，需要设置auth.useDefaultSubversionConfigurationDirectory选择为true，同时需要指定缓存文件路径。
[auth "default"]
...
useDefaultSubversionConfigurationDirectory = true
subversionConfigurationDirectory = /home/user/.subversion5.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来启动修订属性：
SVN_REPOSITORY/
hooks/
pre-revprop-change # for Linux and OS X
pre-revprop-change.bat # for WindowsLinux and OS X系统:
#!/bin/sh exit 0;
Windows系统:
@echo off exit 0
5.9 调整配置：其他选项
[svn]
...
minimalRevision = 1024设置subversion版本的svn.minimalRevision值来指定从哪里开始转换。修订比指定的老蒋不会转换，将不存在于git库。通过该选项来限制修订范围可以减少转换时间。
5.10 运行subgit安装
运行subgit安装命令使subgit开始从subversion转换到git，同时启动之前产生的配置命令synchronization.install。
# subgit install repository.git
SubGit version 2.0.0 ('Patrick') build #2552
Translating Subversion revisions to Git commits...
Subversion revisions translated: 20.
Total time: 10 seconds.
INSTALLATION SUCCESSFUL最初的转换需要一段时间，在这段时间git库是可读的，但是，推是禁用的。
subgit安装命令启动同步安装钩子到git库。已存在的git pre-receive和post-receive钩子将保留并正常执行。
Repository after install command is completed：
GIT_REPOS/
branches/
hooks/
pre-receive # SubGit hook, do not edit or remove
user-pre-receive.sample # user's pre-receive hook template
post-receive # SubGit hook, do not edit or remove
user-post-receive.sample # user's post-receive hook template
logs/
objects/
refs/
svn/
subgit/
config
HEAD一旦安装命令报告成功终止，git用户就可以推代码到git库。新的提交将被转换到新的subversion版本库修订，反之亦然，新的subversion修订将被转换到新的git提交。
5.11 后台执行转换
一旦安装完成后，subgit启动后台进程，定期拉取subversion版本库。每当新的修订被发现，将转换为git提交。这样，git库在大部分时间保持最新。这个后台进程是可选的，可以被killed。当后台进程没有运行时，新的subversion修订将通过git用户推pre-receive钩子来处理。除非在配置文件中禁用，用户推将重启启动后台转换进程。
配置GIT_REPOS/subgit/config文件来定义subgit进程：
[svn] ... fetchInterval = 60 # check for new revisions every 60 seconds ... [daemon] ... idleTimeout = infinity # backgroud process never exits
设置daemon.idleTimeout选项为0，后台转换进程可能会被禁用。在这种情况下，推完成，转换进程立即退出：
[daemon] ... idleTimeout = 0 # backgroud process disabled
强制转换未完成的subversion修订，可以通过下面命令：
# subgit fetch [--async] GIT_REPOS_PATH
或者调用从远程工作树no-op推：
# git push origin +:refs/heads/bogus_branch
上面的命令将尝试删除不存在的远程分支和强制subgit同步git与subversion库。
优雅关闭后台进程命令：
# subgit shutdown repository.git
SubGit version 2.0.0 ('Patrick') build #7777
About to shut down background translation process.
Shutdown request sent to background translation process (pid 4404).
Background translation process has received shutdown request and will exit NOW.
SHUTDOWN SUCCESSFUL5.12 推荐的git客户端配置
git用户将从服务器上克隆git库到本地。有一些配置选项建议添加到.git/config配置文件中。虽说不是必须的，但是会带来更好的用户体验。
Fetch SubGit mapping information:
[remote "origin"]
[remote "origin"]
...
fetch = +refs/svn/map:refs/notes/commitsrefs/notes/commmits包含每个提交到git的映射信息。有了这些记录，git log命令将展示映射信息和提交信息：
# git log
commit bee5c8ae9bd8b2077f1acaedc9982ab4bd84d91b
Author: Alexander Kitaev <kitaev@tmatesoft.com>
Date: Thu Sep 6 18:58:01 2012 +0200
Ugly bug fixed
Notes:
r1 trunkFetch all tags:
[remote "origin"]
...
tagopts = '--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使用，标准的文件名称不会改变。
standard hook name hook name after SubGit is installed pre-receive user-pre-receive post-receive user-post-receive
在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 repository.git
SubGit version 2.0.0 ('Patrick') build #7777
About to shut down background translation process.
Shutdown request sent to background translation process (pid 4900).
Background translation process has received shutdown request and will exit NOW.
SHUTDOWN SUCCESSFUL
SubGit hooks have been removed from Git repository:
/var/git/repository.git
Subversion and Git are no longer kept in sync.在运行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同步:
# make user-pre-receive hook reject all pushes: # cp /var/git/repos.git/hooks/user-pre-receive /var/git/repos.git/hooks/user-pre-receive.backup # echo '#!/bin/sh\nexit 1' > /var/svn/repos/.git/hooks/user-pre-receive # disable synchronization # subgit uninstall /var/git/repos.git
uninstall命令将等待未完成的转换，然后关闭转换后台进程。执行jps命令确保它没有在运行，检查是否有SubGitDaemon java进程。然后，备份一切数据，重新安装subgit、启动同步和git推：
# back up all data # copy -R /var/git/repos.git repos.git.backup # enable synchronization # subgit install /var/git/repos.git # make user-pre-receive hook no longer reject pushes # rm /var/git/repos.git/hooks/user-pre-receive # cp /var/git/repos.git/hooks/user-pre-receive.backup /var/git/repos.git/hooks/user-pre-receive
十一. 系统需求
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/
如需转载请注明出处：SubGit中文手册:获取一个远程subversion库镜像 http://www.ttlsa.com/html/1906.html
本文由主机测评网发布，不代表主机测评网立场，转载联系作者并注明出处：https://zhuji.jb51.net/yunwei/8276.html
