Page tree

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

1. Overview

SubGit is a tool for bidirectional Subversion and Git repositories synchronization. SubGit is written in Java.

Most commonly, SubGit user starts with Subversion repository being configured on the server. Access to Subversion repository is available over network (with HTTP(s), plain svn or svn over SSH protocols) and over the local file system. Correspondingly, users requests are handled by Apache Web Server, svnserve daemon or sshd daemon which invokes svnserve process. Figure 1.1 shows a generic outline of the described configuration.

 Common Subversion Setup

Figure 1.1. Common Subversion Setup

User creates Git repositories with SubGit and configures them so, that these repositories are kept in sync with the remote Subversion repository. Each Git repository mirrors one Subverion project (there could be multiple projects within a single Subversion repository). Changes pushed to the Git repository are instantly translated into Subversion project and vice versa - commits to Subversion project are reflected in the corresponding Git repository.

Optionally, user may enable revision properties on Subversion side by enabling pre-revprop-change hook in Subversion repository - this will let SubGit use single Subversion user account, but this modification is not required, so even Subversion repositories that you do not have shell access to could be mirrored with SubGit. Figure 1.2 shows typical SubGit set up that allows one to use both Subversion and Git and smoothes migration path.

During mirror initialization stage, SubGit translates existing Subversion revisions into a newly created Git repository. There is also a way to skip mirroring and only use SubGit for one-time import from Subversion to Git.

 Git Mirror of a Remote Subversion Repository created with SubGit

Figure 1.2. Git Mirror of a Remote Subversion Repository created with SubGit


  • SubGit creates Git repository that mirrors project in a remote Subversion repositories
  • SubGit could be used for one-time import from Subversion to Git
  • Direct shell access to Subversion repository is not required
  • SubGit grants users with a choice of whether to use Git or Subversion and smoothes migration path
  • SubGit is implemented in Java and needs Java 1.5 or newer

2. SubGit features

Major SubGit benefits are
  • Great translation and initial import performance (in comparison to git-svn)
  • No limits are put on Svn and Git users (contrary to git-svn)
  • Requires no shell access to Subversion repository (contrary to SubGit 1.0.x)

SubGit includes powerful translation engine, which would translate

  • merge tracking information and merge history
  • non-linear Git commits history to Subversion
  • subprojects, tags and branches
  • svn:ignore and .gitignore ignore definitions
  • svn:eol-style and .gitattributes special properties
  • symbolic links
  • commit authors and dates
  • files and directories renames

There are a few limitations on translation (see Translation Limitations). These limitations only affects translation, and do not prevent Git and Subversion from being used to their full extents.

3. Mirror configuration overview

To synchronize Subversion and Git repositories, SubGit maps entities of one system to those of another. One Git repository is always mapped to a single project within Subversion repository. There could be from one to many projects in Subversion repository. Git repository contains SubGit configuration that defines the following information and mappings:
  • Subversion project location within Subversion repository
  • Subversion project branches and tags are mapped to the Git branch and tag references
  • Subversion users are mapped to the Git committers

Above mappings are static and configured within Git repository once before translation and synchronization is started. All mappings and other information is stored in configuration files located in the GIT_REPOS/subgit directory. Following sections describe these mappings in more details.

Subversion is a very powerful system and sets mostly no limits on the repository and project layout. Hence, it may not be always possible to define necessary mappings for any project stored in Subversion repository found out there in the wild. Such unmappable projects would not be handled by SubGit. However, for the most of the Subversion repositories in production use, mappings could be defined and, in most cases, they are detected automatically by SubGit.

3.1 Subversion project location

Subversion repository may contain one or more projects. Project is a location (folder) in Subversion repository which follows Subversion recommended repository layout, i.e. project folder has trunk, branches and tags subfolders:
	/trunk # project's "main line" 
	/branches # contains project feature and version branches, copied from trunk or other branches 
	/tags # contains project tags (trunk and branches snapshots)

It is not necessary for trunk, branches and tags folders to have these exact names, but the roles of these folders are important. Each project could be mapped to a bare Git repository as shown in Figure 3.1 and Figure 3.2 along with the corresponding parts of SubGit configuration file.

 Single Project Repository Mapping

Figure 3.1. Single Project Repository Mapping

SubGit configuration file (single project mapping)

# URL that points to a project root 
# (may be the same as Subversion repository root) 
url = http://host/svn/repos

 Multiple Projects Repository Mapping

Figure 3.2. Multiple Projects Repository Mapping

SubGit configuration file (two projects mapping)

	# project location within Subversion repository 
	url = http://host/svn/repos/project1 
	# project location within Subversion repository 
	url = http://host/svn/repos/project2

3.2 Branches and Tags mapping

For each project mapped to a Git repository, branches and tags are mapped to the corresponding references in the Git repository. SubGit distinguishes the following folders in Subversion project as branches or tags:
  • trunk folder
  • folders in the dedicated branches folder
  • folders in the dedicated shelves folder
  • folders in the dedicated tags folder

Shelves are special kind of branches used by SubGit to represent Git anonymous branches in Subversion repository.

Each folder is mapped to the reference (branch or tag) in the Git repository. For trunk folder the mapping is one-to-one as there could be only one trunk folder (as well as only one master reference in Git) and for other folders wildcard mapping is used. Default mapping and corresponding SubGit configuration file part is shown in Figure 3.3 and Figure 3.4.

Whenever project uses standard folder names (i.e. trunk, branches and tags), SubGit would automatically detect and configure mapping for that project. Otherwise configuration would have to be manually adjusted to include proper paths and references names.

 Default Branches and Tags Mapping

Figure 3.3. Default Branches and Tags Mapping

SubGit configuration file (default branches and tags mapping)

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/*

Note that project2 in Figure 3.2 features non-standard names for trunk, branches and tags folders. Figure 3.4 shows mapping configuration for that project.

SubGit configuration file (non-standard folders names)

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/*

Figure 3.4 outlines combined project and branches mappings for two projects Subversion repository.

 Project and Branches Mapping

Figure 3.4. Project and Branches Mapping

3.3 Authors Mapping

By default there is no explicit authors mapping and the following rules are used for translation:
  • Subversion “svn_user_name” is translated to “svn_user_name <>” in Git
  • Git “Author Name <>” is translated to “Author Name” in Subversion

Additionally to the default rule, explicit authors mapping may be provided by SubGit configuration. Authors mapping is stored in a separate text file which is looked at GIT_REPOS/subgit/authors.txt by default. Mapping file is read in system default encoding.

svn_user_name = Git Name <>

Default authors.txt location may be changed in SubGit configuration file.

# location of the authors mapping file 
authorsFile = subgit/authors.txt 

Authors mapping file (authors.txt) contents may be altered at any time and new mapping becomes effective immediately.

  • No labels