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:

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.3 along with the corresponding parts of SubGit configuration file.

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:

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.5 and Figure 3.6.

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.

Notice that project2 in Figure 3.3 features non-standard names for trunk, branches and tags folders. Figure 3.7 shows mapping configuration for that project.

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

By default there is no explicit authors mapping and the following rules are used for translation:

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 SVN_REPOS/conf/authors.txt by default. Mapping file is read in system default encoding.

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

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

To translate Subversion repository to Git and enabled synchronization, SubGit have to be installed into Subversion repository. SubGit installation consists of three stages: automatic configuration detection, configuration adjustment and installation.

At configuration stage SubGit detects projects and writes down mappings it has found. Then user has a chance to adjust generated configuration. At installation stage SubGit performs actual translation of existing Subversion revisions to Git commits and then turns instant synchronization on. Figure 4.1 schematically shows SubGit installation stages.

It is important to plan in advance what service would be used to access Git repositories and what to work with Subversion ones. Usually Subversion service is left intact and one have to configure Git service account so, that files created or modified on its behalf are readable and writable by Subversion service user and vice versa.

There are basically three possible cases in regards to the services and service accounts. All cases are shown in the diagrams below.

In the most convenient case the same service (Apache HTTP Server) would be used to access both Subversion and Git repositories. Apache HTTP Server user account then would be the only SubGit user (www-data:www-data) as shown in Figure 4.2. In this case no changes are needed.

Different services may run on behalf of the same user account as in Figure 4.3. In this case there is still single SubGit user, www-data:www-data and no changes have to be made.

When different services would be used (e.g. SSH for Git and svnserve for Subversion) and ran on behalf of the different service accounts, then each service account must belong to all other accounts primary groups in addition to its own primary group, like it is shown in Figure 4.4 where svn:svn user also belongs to the git group and git:git user also belongs to the svn group.

For instance, in case of the three accounts, they would belong to the following groups:

Following commands show how to add user to another account primary group:

Alternatively, in Figure 4.4 scenario all accounts may share the same primary group.

To display and change user's primary group one may use the following commands:

Run SubGit configure command to make SubGit detect projects in Subversion repository and generate initial SubGit configuration for them. One have to run configure command on behalf of the same user account that would be used to access Subversion or Git repository. Use sudo command on Linux or OS X or Administrator account on Windows if necessary. Examples below assume Ubuntu Linux and commands are ran on behalf of www-data user that runs Apache Web Server on that system.

When configure command is run on a repository with a single project one will get the following output:

When SubGit configure is run on repository with two projects, mapping will be displayed for the both detected projects:

At configuration stage SubGit does not actually create Git repositories, but generates configuration file with the information on detected projects and mappings. Changes to Subversion repository made by the configure command are shown below:

SubGit configure command detects projects in Subversion repository and writes configuration and mappings to the SVN_REPOS/conf/subgit.conf file. Generated configuration have to be adjusted or extended when:

subgit.conf file generated for a single-project Subversion repository will look like this (some of the less frequently used options are not shown here):

Enable shared access: 

Set core.shared option to true (default is false) if you plan Subversion and Git repositories to be accessed by different user accounts (see Section 4.2).

Provide authors mapping:  Write Subversion users to Git authors mapping to conf/authors.txt file (see Section 3.3, “Authors Mapping”). For instance:

Or specify existing authors mapping file: 

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.

Adjust Git repository location: 

Specify path whether you would like Git repository to be created. By default, Git repositories are created within Subversion repository, at SVN_REPOS/.git in a single-project repository and at SVN_REPOS/git/project.git in a multi-project repository. This way allows one to copy or move Subversion and connected Git repositories with a single filesystem command. Change Git repository path to the one which fits your environment better.

Set path encoding to be used in Git repository: 

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.

Set revision to start translation from: 

Set git.minimalRevision to Subversion revision from which translation should be started. Revisions older than specified would not be translated and would not be present in the Git repository. Limiting range of revisions with this option may reduce initial translation time.

Add projects that have not being detected automatically: 

Some projects with non-standard layout may not be detected by SubGit (see Section 3.1, “Projects mapping” and Section 3.2, “Branches and Tags mapping”). In case it is possible to distinguish trunk, branches and tags directories for those projects one may add them manually to the configuration file. Consider the following layout for project and library project:

Corresponding [git] sections should be added to subgit.conf file to enable translation and synchronizations of these projects:

Note that git.translationRoot options have similar value in both projects. This option specify a path relative to which branches and tags mapping paths are expanded.

One will find more options in the conf/subgit.conf file, as well as documentation on what these options control.

Run SubGit install command to make SubGit create Git repositories, perform initial translation from Subversion to Git and to enable synchronization.One have to run configure command on behalf of the same user account that would be used to access Subversion or Git repository. Use sudo command on Linux or OS X or Administrator account on Windows if necessary. Examples below assume Ubuntu Linux and commands are ran on behalf of www-data user that runs Apache Web Server on that system.

install command uses configuration previously generated by configure command or perform configuration stage itself in case pregenerated configuration is not present. Subgit install command output when run on a single-project Subversion repository is shown below:

Initial translation may take a while, however it would not affect Subversion repository - it remains fully functional during initial translation time.

SubGit install command creates Git repository and enables synchronization by installing hooks. Existing Subversion pre-commit and post-commit hooks are preserved and executed normally.

As soon as install command reports successful termination, commits to Subversion repository will be immediately translated to the corresponding Git repository and vice versa - pushes to Git repository from its clones will be immediately translated to Subversion repository. With SubGit no special actions are required to maintain Subversion and Git repositories synchronized.

Git users will clone Git repository on the server side to start working with the project locally. There are number of configuration options that is recommended to add to the clone's .git/config configuration file. These options are not required, but merely recommended for better user experience.

Fetch SubGit mapping information: 

refs/notes/commmits reference points to the so called notes that contains Subversion to Git mapping information for each commit. With these notes fetched git log command will show mapping information alongside with the commit message in the log output:

Fetch all tags: 

--tags option will force Git to fetch all tags, even those unreachable from the current branch. These may be convenient in case user would like to see or check out tag set on the other branch.

In order to enable synchronization of Subversion and Git repositories, SubGit installs hooks both into Subversion and Git repository that need to be synchronized. These hooks are:

Presence of these hooks is crucial for SubGit to function properly, and users should never modify or remove these hook scripts. If necessary, above hooks functionality should be placed into user-* scripts that would be called by SubGit at appropriate moments. SubGit install command takes care of already existing hooks and automatically places their contents into the corresponding user-* script files (see Figure 4.5, “Repository after install command is completed”).

Table below shows correspondence between standard hook scripts file names and file names that should be used to put hook functionality into after SubGit is installed. Hooks parameters and return code processing rules are not affected by SubGit. Hooks that are not listed in the table are not used by SubGit and their standard file names are not changed.

On Windows OS .cmd or .bat extension should be added to Subversion hook file names.

SubGit configuration could be changed after SubGit is installed into repository. Some of the changes become effective immediately and others require subgit install or subgit install --rebuild command to be executed in order for the changes to be applied.

As with all other SubGit commands, subgit install command should be ran on behalf of the user that runs service that access Subversion or Git repository (see Section 4.2, “Setup Service Accounts”).

Changes that become effective immediately: 

Changes that become effective after 'subgit install' is run: 

subgit install command will validate changes made to the subgit.conf and apply these changes. If necessary, file permissions would be updated and new Git repositories would be created.

Changes that become effective after 'subgit install --rebuild' is run: 

--rebuild option of the install command will make SubGit to back up existing Git repositories and to regenerate them using new mapping and translation options.

Original configuration: 

Goal: 

Steps: 

1) Install SubGit into all Subversion repositories:

Refer to Chapter 4, Installing SubGit into Repository for more details on how to install SubGit into repository.

Make sure that subgit install command is run on behalf of the Apache user, in that case www-data.

2) Install git-http-backend which is a part of Git 1.6.6 or newer

3) Add Git directives to the apache configuration file (added lines are shown with bold font):

More configuration examples could be found at the git-http-backend documentation page.

4) Reload Apache configuration:

Users may now access Git repositories at:

Users should use same credentials they are using to access Subversion repository.

Original configuration: 

Goal: 

Steps: 

1) Install SubGit into all Subversion repositories:

Refer to Chapter 4, Installing SubGit into Repository for more details on how to install SubGit into repository.

Edit repository/conf/subgit.conf file. In this configuration it is important to set SubGit core.shared option to true, because different users will access Subversion and Git repositories.

Run subgit install to finish SubGit installation into repository:

Make sure that SubGit configure and install commands are ran on behalf of the Apache user, in that case www-data.

2) Create git user and set up users groups:

Now git and www-data users shares the same set of groups. See Section 4.2, “Setup Service Accounts” for more details on service users configuration.

4) Configure SSH access:

Add actual Git users SSH public keys to the /home/git/.ssh/authorized_keys file and ensure that sshd daemon is running. For security reasons you may like to look through the /etc/ssh/sshd_config file or its analogue on your system to check that key pair authentication is the only one enabled for the git user.

Users will be able to access Git repositories at:

There is a good article describing how to set up SSH access for Git repository in more details.

Subversion repositories will remain available over HTTP(s) just as before at:

Original configuration: 

Goal: 

Steps: 

1) Install SubGit into all Subversion repositories:

Run subgit install command as Administrator user.

2) Get portable Git

As Administrator:

3) Extend Apache configuration

As Administrator, create new C:\Program Files\WANdisco\uberSVN\conf\conf.d\88-subgit.conf configuration file:

3) Restart WANdisco Apache service

In the Services section of the Windows Control Panel, ensure that WANdisco Apache service is run on behalf of Administrator user and restart this service.

Users will be able to access Git repositories at:

Git users should use same credentials they are using to access Subversion repository.

Subversion repositories will remain available over HTTP(s) just as before at: