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
/project /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.
Figure 3.1. 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
Figure 3.2. 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/project2
3.2 Branches and Tags mapping
- 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.
Figure 3.3. 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/*
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)
[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/*
Figure 3.4 outlines combined project and branches mappings for two projects Subversion repository.
Figure 3.4. Project and Branches Mapping