Page History

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.

Anchor
Branches and tags in SVN Branches and tags in SVN

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

...

A graphical representation of the explained SVN concepts:

Branches and Tags in Git

Anchor
Branches and tags in Git 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 containing 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 timefile tree snapshot along with author and date information. Commit is identified by its SHA1 hash value.
• 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:

Mapping Configuration Options

Anchor
Mapping configuration options 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 , that is situated in subgit subdirectory inside a newly created Git repository:

/GIT_REPOS_PATH
    …
    /subgit
       …
       PATH/subgit/config

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

...

• SVN project location:
  • url - a URL leading to the SVN project.
     
• Branches and tags mapping rules:
  • 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.
     
• Refining mapping rules:
  • 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.

svn.url

Anchor
svn.url svn.url

This option sets a URL to the SVN project, that is being translated into Git repository. SubGit translates a SVN project into a Git repository: not whole SVN repository to Git repository:

...

• Mapping-option - essentially, a mapping option: trunk, branches, tags or shelves.
• Subversion-Path-Pattern – a SVN directory path relative to `svn.url`.
• Git-Reference-Pattern – a path inside Git repository where references will be stored.

svn.trunk

Anchor
svn.trunk svn.trunk

This setting establishes a correspondence between SVN *trunk* and Git branch that represents the main line of development. Assuming, that SVN "main line of development" is being kept in a directory named trunk and Git master branch represents the "main line" in Git, the mapping may look like this:

...

svn.

...

branches

This setting establishes a correspondence between SVN and Git branches. Its default value assumes standard SVN layout is used, i.e. that a SVN project branches reside in a directory named branches:

...

branches = branches/*:refs/heads/*
branches = feature_*:refs/heads/features/*
branches = hotfix/*_*:refs/heads/hotfix/*/*
branches = special_branch:refs/heads/special_branch

svn.tags

Anchor
svn.tags svn.tags

This setting establishes a correspondence between SVN and Git tags. The default value assumes standard SVN layout:

...

tags = 1.0/*:refs/tags/1.0/*
tags = 1.5.*:refs/tags/1.5/*
tags = tags/2.0.*/*:refs/tags/2.0/*/*
tags = tags/special_tag:refs/tags/special_tag

svn.shelves

Anchor
svn.shelves svn.shelves

Shelves are special entities being introduced by SubGit. SubGit creates shelves when it cannot determine branch name where particular commit belongs to. For example, a shelf will appear in SVN after in the following case:

...

In such case, SubGit will be able to see all the commits, but won’t be able to recognize the branch name to which they belong. So it will place them into shelves SVN directory.
Find more details on the shelves in See a blog post "What are shelves really?" blog post.   for more details on shelves.

The setting sets a directory in SVN where shelves will be stored:

...

svn.excludeBranches, svn.excludeTags

Anchor
svn.excludeBranches svn.excludeBranches

These two settings do reverse job: while all the previous settings tell what to include, these tell SubGit which branches or tags to be excluded from translation. They are interchangeable, any of the two can be used to exclude both *branches* and *tags*.

...

    http://example.com/svn/repository/Project1/branches/feature_*

svn.excludePath, svn.includePath

Anchor
svn.excludePath svn.excludePath

These are settings that provide a possibility to exclude (or vice versa, include) some files from translation. It may be useful e.g. if you have some big files in SVN that you don't want to be present in Git repository. The syntax is simple:

...