5. Creating Git Mirror of a Subversion Repository

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.

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

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.

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.