This story is based completely on a personal experience of somebody quite dumb who’s tried to install SubGit and succeeded. It all began when I’ve decided to stop being oldschool and desired to move my humble Python project from SVN to Git. I heard about SubGit so I googled.

To define user’s repository layout SubGit uses branches mapping. 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 could be used. Attention here, as what is left out is not translated by SubGit. 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.

Many questions arise when it comes to the topic what are shelves, how to use them and why could it be useful to do so at all. To lit some light on the question at first it’s needed to explain a bit the difference between branches in Git and branches in SVN. In SVN branch is represented by a directory and files inside that directory are commits. In Git there is no direct association between a commit and a branch. Commits in Git contain various information e.g. unique SHA1, author, time and date of creation, SHA1 of the parent commit, but do not contain the name of the branch in which they have been created. Therefore to translate commits from Git to SVN and to assign all commits to their branches SubGit uses a special algorithm that logically analyses all given data and makes usually a very wise conclusion about to where each commit belongs. But sometimes it is not quite obvious a decision as in some particular cases it’s not possible to determine one commit’s branch. And at that exact moment shelves come into the scene.