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
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" –
features – and three for "stable snapshots" –
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.