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.