The Subversion development team recommends to follow certain repository layout in which strategically named Subversion directories convey meaning about the data they hold: “main line”, or trunk, of development; some branches, which are divergent copies of development lines; and some tags, which are named, stable snapshots of a particular line of development. An SVN repository can contain many projects, each of them may have its own trunk, branches, and tags, thus commonly the recommended layout for a Subversion repository is organized in the following way:
/repository /project_1 /trunk /branches /tags /project_2 /trunk /branches /tags … /project_N /trunk /branches /tags |
SubGit translates an SVN project to a Git repository: by default, SVN trunk is translated to Git master branch, each branch from SVN branches directory is translated to a Git branch with the same name as SVN branch directory has, and each tag from SVN tags directory is translated to a lightweight Git tag.
During the initial configuration phase, SubGit creates a configuration file and fulfills it with defaults values, and, particularly, it creates default mapping scheme:
trunk = trunk:refs/heads/master branches = branches/*:refs/heads/* tags = tags/*:refs/tags/* shelves = shelves/*:refs/shelves/* |
This default mapping reflects the recommended SVN project layout: it maps SVN trunk to Git master branch, SVN branches and tags to Git branches and tags. Additionally, it maps anonymous Git commits into an SVN shelves directories, find more details on shelves in the blog post.
Another possible case is a layout that follows recommended SVN project structure, but doesn't follow recommended naming convention, for example:
/svn /repository /project /main /offshoots /snapshots |
The main
directory represents a "main line" of development (matching to trunk in the meaning), the offshoots
directory contains "divergent copies" (that is, branches), and the snapshots
directory contains "stable snapshots" – that is, tags. In such case, the mapping scheme is still the same, but SVN directories names must be changed to actual ones:
trunk = main:refs/heads/master branches = offshoots/*:refs/heads/* tags = snapshots/*:refs/tags/* shelves = shelves/*:refs/shelves/* |
There may be more than one directory containing SVN "divergent copies" and/or "stable snapshots", for example:
/svn /repository /project /trunk /branches /bugs /features /tags /major_releases /minor_releases |
The layout is near to recommended: the trunk
directory represents trunk, but there are three different directories for "divergent copies" – branches
, bugs
and features
– and three for "stable snapshots" – tags
, major_releases
and minor_releases
. To translate all the branches and tags, all those directories should be added to the mapping configuration and mapped to its own Git namespace:
trunk = trunk:refs/heads/master branches = branches/*:refs/heads/* branches = features/*:refs/heads/features/* branches = bugs/*:refs/bugs/* tags = tags/*:refs/tags/* tags = major_releases/*:refs/major_releases/* tags = minor_releases/*:refs/minor_releases/* shelves = shelves/*:refs/shelves/* |
SubGit is able to create suitable mapping configuration automatically when subgit configure
command is invoked with --layout auto
and --trunk
options, find more details on how to use automated mapping creation in the user manual.