Page History

...

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.

...

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:

...

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

• 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

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:

...

The next four options – trunk, branches, tags, shelves – actually tell SubGit how SVN to Git entities match to each other. Generic mapping syntax is:

    <Mapping-option> = <Subversion-Path-Pattern>:<Git-Reference-Pattern>

where

• 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

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:

trunk = trunk:refs/heads/master

where

• the first trunk is a mapping option name, determining which entity is being mapped.
• the second trunk is a path to SVN directory, which plays a role of trunk. This path is relative to

...

• specified svn.url i.e. the full path to that directory consists of the URL and this path. Thus, suppose the URL is set like follows:

          url = http://example.com/svn/repository/project1

...

           http://example.com/svn/repository/Project1/trunk

• refs/heads/master – a path in Git repository, where the branch reference is kept. In this case, SVN trunk is being translated into Git master branch.

There are few rules that apply to the `svnsvn.trunk` trunk option:

...