Branches mapping overview.

Branches mapping is a set of rules that establish a correspondence between SVN and Git branches and tags. These rules are defined by branches mapping configuration options in SubGit configuration file.

Branches and Tags in Subversion.

There are few key Subversion concepts, that matter in the context of SubGit mapping process:

• repository – a central store, root directory, that holds all data in the form of a filesystem tree. A repository contains one or more projects.
• project – a data part in a repository, that can be logically distinguished from the rest, like a distinct software product or a library. Most projects have their own recognizable "main lines" and "divergent copies" of development.
• branch - a distinct line of development that exists independently of all others, yet still shares a common history. A branch is a directory within repository or project, which contains all files of that particular line of development.
• tag – a named snapshot of a development line in time. A tag is also a directory within repository or project. The main difference between branch and tag is that tags are supposed to be unchanged with time.
• trunk – a branch, that represents the main line of development. It's a directory within repository or project, which contains the main line of development.
• revision – a certain state of the filesystem tree, that has an assigned number and commentary.
• layout – a way how repository or project filesystem tree is organized.
• standard layout – a repository layout, that Subversion development team recommends to follow. According to that layout, each project resides in its own subdirectory within a repository and has three subdirectories for trunk, branches and tags.

A SVN repository can be organized in any way and SubGit can deal with any possible SVN repository layout.

A graphical representation of the explained SVN concepts:

Branches and Tags in Git

Unlike SVN, which stores data in the form of a filesystem tree, Git represents its data as a set of snapshots of a filesystem, that is being stored in Git's objects database. Due to this difference, most of Git concepts differ from their SVN counterparts albeit have the same names:

• repository – a directory, that contains Git database and metadata.
• commit – a Git object, that contains a pointer to a data snapshot in Git database. Essentially, the commit is a hash-named file in Git database, that contains a reference to a tree object, representing a data snapshot in time.
• branch – a reference to certain commit; a file in a Git database that contains a hash of a certain commit, thus referencing that particular commit.
• master branch – a default branch called master that's being created along with new repository. By agreement, it represents the main line of development, but technically it's just another branch.
• tag – like a branch, a reference to a commit - a file in a Git database that contains a hash of that particular commit. Git supports two kinds of *tags*: *lightweight* and *annotated*; SubGit supports only *lightweight tags*.

A graphical representation of the explained Git concepts:

SVN to Git mapping

Mapping Configuration Options

All the mapping configuration assembled in SubGit configuration file. The configuration file is being created at the SVN-to-Git translation beginning by SubGit's configure subcommand. The file is situated in subgit subdirectory inside a newly created Git repository:

/GIT_REPOS_PATH
    …
    /subgit
       …
       config

Here is an example of how the [svn] of the configuration file may look like:

[svn]
    url = http://svn.example.com/svn/repository_1/project_1
    trunk = trunk:refs/heads/master
    branches = branches/*:refs/heads/project_1/*
    branches = features_*:refs/heads/features/*
    tags = tags/*:refs/tags/*
    shelves = shelves/*:refs/shelves/*
    excludeBranches = features/feat_4510
    excludePath = *.exe

All the mapping settings reside in [svn] configurations section. There are three main settings groups:

* A SVN repository path setting:
- url - a URL leading to the SVN project.

* Direct mapping settings *[mapping settings per se]*:
- trunk - a path, relative to the URL, that leads to project's trunk.
- branches - a relative path to a directory, containing branches, or a path to a particular branch.
- tags - a relative path to a directory, containing tags, or a path to a particular tag.
- shelves - a relative path to a directory, where *shelves* will be kept.

* Mapping fine tuning settings:
- excludeBranches - a relative path or path pattern with one wildcard, that point to branches or tags, that should be excluded from translation.
- excludeTags - same as *excludeBranches*.
- excludePath - an expression, representing files to be excluded from the translation.
- includePath - an expression, representing files to be included in the translation.