5.1. Installation Stages
To translate Subversion repository to Git and to enable bi-directional synchronization, one have to use SubGit to create and configure Git repository. Mirror creation consists of three stages: repository creation, configuration adjustment and installation.
Figure 5.1. Mirror Creation Stages
At configuration stage SubGit creates Git repositories and stores default mirror configuration into it. Then user has a chance to adjust generated configuration. At the installation stage SubGit performs actual translation of existing Subversion revisions into Git commits and then turns synchronization on. Figure 5.1 schematically shows SubGit installation stages.
Figure 5.1. Mirror Creation Stages
At configuration stage SubGit creates Git repositories and stores default mirror configuration into it. Then user has a chance to adjust generated configuration. At the installation stage SubGit performs actual translation of existing Subversion revisions into Git commits and then turns synchronization on. Figure 5.1 schematically shows SubGit installation stages.
5.2. Run `subgit configure`
Run SubGit configure command to make SubGit create empty bare Git repository and link it with a project in Subversion.When running configure command user have to specify Subversion project URL and, optionally, minimal revision to start synchronization from:
$ 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
At configuration stage SubGit does not establish connect with Subversion repository, but generates configuration file with the information necessary to proceed with installation. Files added to the Git repository by the configure command are shown below:
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
HEAD
When running configure command user have to specify Subversion project URL and, optionally, minimal revision to start synchronization from:
$ 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
At configuration stage SubGit does not establish connect with Subversion repository, but generates configuration file with the information necessary to proceed with installation. Files added to the Git repository by the configure command are shown below:
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
HEAD
5.3. Adjust configuration: overview
SubGit configure command creates bare empty Git repository and writes default configuration and mappings to the GIT_REPOS/subgit/config file. Generated default configuration have to be adjusted before proceeding with install stage, in particular user have to provide credentials (or specify where to find them) to let SubGit access Subversion repository. config file generated by default will look like this (some of the less frequently used options are not shown here):
[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/subversion
Paths in subgit/config file:
File system paths in subgit/config file could be specified in relative or absolute form. Relative paths are those that do not start with ‘/’ or drive letter on Windows OS. Relative paths are treated as relative to the Git repository root directory.
[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/subversion
Paths in subgit/config file:
File system paths in subgit/config file could be specified in relative or absolute form. Relative paths are those that do not start with ‘/’ or drive letter on Windows OS. Relative paths are treated as relative to the Git repository root directory.
5.4. Adjust configuration: provide authors mapping
Write Subversion users to Git authors mapping to conf/authors.txt file (see Section 3.3, “Authors Mapping”). For instance:
conf/authors.txt:
semen = Semen Vadishev <vadishev@tmatesoft.com>
dmitry = Dmitry Pavlenko <pavlenko@tmatesoft.com>
Or specify existing authors mapping file:
[core]
...
authorsFile = /var/git/company-authors-mapping.txt
Specify path to the authors mapping file (see Section 3.3) as core.authorsFile option value. Path is either relative to the Subversion repository root (e.g. conf/authors.txt expands to SVN_REPOS/conf/authors.txt) or absolute.
Provide default domain for missing emails:
[core]
...
defaultDomain = company.com
Email has to be part of the Git author information and some of Git operations may fail when email is not present. SubGit will use core.defaultDomain value to generate author’s email when author is not found in the authors mapping or in case authors mapping doesn’t provide email.
Tip: Add author mappings for as many of you team members as possible, even if they don’t use Git as the log history will be more consistent.
conf/authors.txt: semen = Semen Vadishev <vadishev@tmatesoft.com> dmitry = Dmitry Pavlenko <pavlenko@tmatesoft.com>
Or specify existing authors mapping file:
[core] ... authorsFile = /var/git/company-authors-mapping.txt
Specify path to the authors mapping file (see Section 3.3) as core.authorsFile option value. Path is either relative to the Subversion repository root (e.g. conf/authors.txt expands to SVN_REPOS/conf/authors.txt) or absolute.
Provide default domain for missing emails:
[core] ... defaultDomain = company.com
Email has to be part of the Git author information and some of Git operations may fail when email is not present. SubGit will use core.defaultDomain value to generate author’s email when author is not found in the authors mapping or in case authors mapping doesn’t provide email.
Tip: Add author mappings for as many of you team members as possible, even if they don’t use Git as the log history will be more consistent.
5.5. Adjust configuration: path encoding
[core]
...
pathEncoding = UTF-8
Git stores paths as a sequence of bytes, without encoding specified. Usually paths ends up in Git as-is, i.e. in the local file system encoding. Use git.pathEncoding option to specify encoding to use when translating string path found in Subversion repository to Git. Most modern file systems use or could be configured to use UTF-8 encoding and this is default and recommended value.
[core] ... pathEncoding = UTF-8
Git stores paths as a sequence of bytes, without encoding specified. Usually paths ends up in Git as-is, i.e. in the local file system encoding. Use git.pathEncoding option to specify encoding to use when translating string path found in Subversion repository to Git. Most modern file systems use or could be configured to use UTF-8 encoding and this is default and recommended value.
5.6. Adjust configuration: branches mapping
[svn]
...
url = http://host/svn/repos
svn.url option value specifies project location. It is used as the root URL relative to which mappings paths are treated.
[svn]
...
trunk = trunk:refs/heads/master
branches = branches/*:refs/heads/*
tags = tags/*:refs/tags/*
shelves = shelves/*:refs/shelves/*
There are four kinds of branches that have to be mapped, each represented by its own option: trunk, branches, tags and shelves. Each option establishes SVN_PATH to GIT_REFERENCE correspondence for a particular kind of entity. Mapping syntax for trunk is:
trunk = SVN_PATH:GIT_REFERENCE
svn.trunk option allows to specify single SVN_PATH:GI_REFERENCE mapping as its value. SVN_PATH is a path relative to the project svn.url location and GIT_REFERENCE is a git reference e.g. refs/heads/master. Mapping meaning is that changes made on or below SVN_PATH in Subversion project translated to the Git commits on GIT_REFERENCE and conversely, commits on GIT_REFERENCE would be translated to the changes below SVN_PATH. Mapping syntax for branches, tags and shelves is:
branches = SVN_PATH[/*]:GIT_REFERENCE[/*]
Mapping could be either one-to-one or many-to-many, in other words when ‘*’ wildcard is used it should be present in the both sides of mapping. In order to specify multiple mappings each mapping must be defined as a separate option, see example below:
branches = branches/*:refs/heads/*
branches = release_branches/b1:refs/release/b1
Above mapping maps all branches in Subversion branches directory to the Git refs/heads namespace and, additionally, maps single release_branches/b1 branch to refs/releases/b1 Git branch reference.
Be careful when specifying mapping, it would not be possible to adjust it when synchronization is enabled. Only branches and tags that are included in the mapping will be imported and kept in sync by SubGit.
[svn] ... url = http://host/svn/repos
svn.url option value specifies project location. It is used as the root URL relative to which mappings paths are treated.
[svn] ... trunk = trunk:refs/heads/master branches = branches/*:refs/heads/* tags = tags/*:refs/tags/* shelves = shelves/*:refs/shelves/*
There are four kinds of branches that have to be mapped, each represented by its own option: trunk, branches, tags and shelves. Each option establishes SVN_PATH to GIT_REFERENCE correspondence for a particular kind of entity. Mapping syntax for trunk is:
trunk = SVN_PATH:GIT_REFERENCE
svn.trunk option allows to specify single SVN_PATH:GI_REFERENCE mapping as its value. SVN_PATH is a path relative to the project svn.url location and GIT_REFERENCE is a git reference e.g. refs/heads/master. Mapping meaning is that changes made on or below SVN_PATH in Subversion project translated to the Git commits on GIT_REFERENCE and conversely, commits on GIT_REFERENCE would be translated to the changes below SVN_PATH. Mapping syntax for branches, tags and shelves is:
branches = SVN_PATH[/*]:GIT_REFERENCE[/*]
Mapping could be either one-to-one or many-to-many, in other words when ‘*’ wildcard is used it should be present in the both sides of mapping. In order to specify multiple mappings each mapping must be defined as a separate option, see example below:
branches = branches/*:refs/heads/* branches = release_branches/b1:refs/release/b1
Above mapping maps all branches in Subversion branches directory to the Git refs/heads namespace and, additionally, maps single release_branches/b1 branch to refs/releases/b1 Git branch reference.
Be careful when specifying mapping, it would not be possible to adjust it when synchronization is enabled. Only branches and tags that are included in the mapping will be imported and kept in sync by SubGit.