SVN Users and Git Authors
Both Subversion and Git keep authors in commits, but those authors differ.
In SVN, the author is being stored as an unversioned revision property
svn:author. Every time a Subversion user makes a commit, SVN creates a new revision and sets this revision
svn:author property to that exact user's name, for example, johndoe:
Git also stores author name along with commits, but this name differs from that in SVN: whereas SVN stores actual username, Git user identity consists of a name and email:
Those name and email don't relate to an actual username that is used to login to Git repository, they are being set in Git configuration, for example then may be set by the commands below:
The Git user John Doe is then referred as
This exact line then appears as the author name in every commit John Doe makes.
It worth to mention that Git holds not only author name, but also a committer name:
Pro Git book describes the difference between those names as follows: the author is the person who originally wrote the work, whereas the committer is the person who last applied the work. So, if you send in a patch to a project and one of the core members applies the patch, both of you get credit – you as the author, and the core member as the committer.
SubGit translates Git author name, so committer name doesn't mean much for the SVN-to-Git translation process.
Authors mapping affects licensing
Note, that SubGit uses authors names to count licensed users, see Licensing manual for details.
All the configuration options reside in SubGit configuration file, that is situated in subgit subdirectory inside a newly created Git repository:
There are two configuration options that relate to authors:
this option represents a path to the authors mapping file or authors mapping helper program. The path is either relative to the Git repository or absolute. The default value is:
There may be more that one
authorsFileoption set in the file:
All the mentioned files content is being merged into a full list. If an SVN username appears more than once – only its first occurrence will be applied. For example, if an SVN username
johndoeappears in both authors files:
In this case, the SVN name
johndoeis being mapped to Git name
John Doe <firstname.lastname@example.org>as it appears first in the list.
this option represents a domain name that is being used to construct a Git user email address in case if no explicit authors mapping has been provided. If the option is not set, Git user email appears empty in commits – a pair of angle brackets with nothing in between:
Authors mapping for SVN server 1.7.20, 1.8.12 or 1.9.0
If you are using SVN server 1.7.20, 1.8.12 or 1.9.0 or later, and the SVN repository is being accessed over
http(s):// protocol, then
pre-revprop-change hook may need to be enabled in SVN repository, see SVN authors are not being set correctly article.
Automatic Authors Mapping
When SubGit starts translation between SVN and Git, it looks for authors mapping files or authors helper programs. If none of them present, it generates the mapping automatically, following these rules for the translation:
- Subversion svn_user_name is being translated to svn_user_name <svn_user_name@defaultDomain> in Git
- Git Author Name <email@example.com> is translated to Author Name in Subversion
defaultDomain here stands for the
core.defaultDomain SubGit configuration option.
subgit configure call, this setting is being set to the hostname. Also, if
subgit configure is invoked with
--layout auto option, SubGit connects to specified SVN project, checks its history and generates authors mapping using found SVN usernames and given defaultDomain, then SubGit fills up the default authors file with the resulting mapping.
For example, suppose, the defaultDomain is set like follows:
A user made commits in SVN under john_doe SVN account. When SubGit translates these commits to Git, it sets author name in Git commits in the following way:
Similarly, Git commits that made by John Doe <firstname.lastname@example.org> Git user appears in SVN with John Doe author name.
The authors mapping file is actually just a text file filled with SVN username - Git author pairs. Each pair maps SVN username to Git author like:
svn_user_name = Git Name <email@example.com>
e.g. for a user named John Doe, the mapping can be set as:
john_doe = John Doe <firstname.lastname@example.org>
Every SVN or Git user that makes commits either to SVN project or to mirrored Git repository is supposed to have the author mapping pair here in the authors file and each author pair must reside on a new line.
During SVN to Git translation, SubGit takes a SVN revision authors name and search the authors file for a match. If there is a matching line in the file - SubGit uses appropriate Git username to create commit in Git; otherwise, if there is not - SubGit will construct a Git commit author name using automatic mapping. And vice versa - during Git commit to SVN revision translate, SubGit searches the file and use appropriate SVN username to create the SVN revision; if there's no matching pair in the file - automatic mapping is used.
Note, that it is possible to map two different SVN usernames to the same Git author - for cases, say, when one team member uses two identities to make commits or some SVN username was renamed some time. In such case there might be such configuration created:
john_doe = John Doe <email@example.com> johndoe = John Doe <firstname.lastname@example.org>
Every revision that was made by
johndoe will be translated to Git commit with author name
John Doe <email@example.com>. But note, when this Git user makes commit in Git and this commit is being translated to SVN, the author on the SVN side will be set to first SVN username that matches particular Git name in the authors file. That is if those two authors mapping lines appear in the authors file in that exact order -
john_doe first, then
johndoe - then SVN revision author will always be set to
john_doe when John Doe's Git commits are being translated to SVN.
Similarly, one SVN user can be mapped to different Git authors, e.g.:
jdoe = John Doe <firstname.lastname@example.org> jdoe = Jane Doe <email@example.com> jdoe = James Doe <firstname.lastname@example.org>
and again, every Git commit made by those authors will be translated to SVN with revision author set to
jdoe; but SVN revisions made by that
jdoe SVN user will always be set to first matching Git user in the authors file -
John Doe <email@example.com> in this particular case.
Scriptable Authors Mapping
In addition to the authors file, there's another way to provide SVN to Git authors mapping using authors helper program. The authors helper is an executable - script or binary - that is able to read data from standard input and provide its work result to the standard output. The data helper reads from input and the data helper provides to output must fulfill certain format:
for Git to Subversion mapping: INPUT: Author Name author email OUTPUT: Subversionusername
for Subversion to Git mapping:
INPUT: Subversionusername OUTPUT: Author Name author email
Every time SubGit finds an author name during translation, it invokes the authors mapping helper program, passes the name to it and expects the helper to answer with matching author name.
The authors helper program might be extremely useful especially when you have many authors and the authors list is constantly changing - new users are being added, names and emails changes and so on. If you use some catalog to store accounts - LDAP, Active Directory, OpenID and so forth - you can create a script that will gather needed information from the catalog and provide it to SubGit.
During configuration or installation phase SubGit places simple
authors.sh script into
subgit/samples directory. This script doesn't do much useful, it's just some 'proof of concept' that demonstrates how input data is being read and output data provided. The script as simple as:
while read input do if [ -z "$name" ]; then name="$input" elif [ -z "$email" ]; then email="$input" fi done if [ -z "$email" ]; then echo Full Name echo firstname.lastname@example.org else echo shortSvnUserName fi exit 0;
Depending on what was sent to its input script returns either Git author name and email or SVN short name. It can be extended to, say, receive the data from catalog or database thereby facilitate the authors mapping.