SVN Users and Git Authors
Anchor | ||||
---|---|---|---|---|
|
Both Subversion and Git keep authors names in commits, but those authors entities differ in those two systems authors differ.
In SVN, the author is being stored is stored as an unversioned revision property, namely property svn:author
. Every time a Subversion user makes a commit, SVN creates a new revision and sets this revision svn:author
property to be equal to that exact user's name, e.g. johndoe in this case:
...
, for example, johndoe:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
$ svn proplist -v --revprop --revision 163 Unversioned properties on revision 163: svn:author johndoe svn:date 2017-06-07T15:22:15.655243Z svn:log initial layout for the project |
...
Git , in turn, also stores author 's name along with every commitcommits, but this name differs from that in SVN: whereas SVN stores actual username, Git stores a name that's set by user.name
Git directive, e.g., by global setting:user identity consists of a name and email:
No Format |
---|
Git User <gituser@domain.com> |
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, they may be set by the commands:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
$ git config --global user.name "John Doe" |
...
and in addition to the user.name
Git relies upon user.email
that can be set as:
$ git config --global user.email johndoe@example.com |
Actually, both user.name
and user.email
are parts of Git user identity, i.e. a Git user is being mentioned as
Git User <gituser@domain.com>
everywhere; e.g. the user John Doe we've set above will be referred as:The Git user John Doe is then referred as
No Format |
---|
John Doe <johndoe@example.com> |
and this This exact line will appear then appears as the author name when the user makes some commit in Git. Still, it in every commit that John Doe makes.
It worth to mention for completeness sake that Git stores holds not only author name, but also a committer name along with every commit and they may differ in some cases::
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
$ git cat-file commit HEAD
tree 905df23db37b33320483fc6676bfc684078ed248
parent 4a0cf06baa9aefaa20a13820265ef401d7b1c2b6
author John Doe <johndoe@example.com> 1496849115 +0000
committer Jane Doe <janedoe@example.com> 1496849115 +0000 |
...
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.
Most often though, author and committer names are the same since most of the programmers commit their work by themselves. Also, SubGit works with Git author name, so committer name doesn't mean much for the SVN-to-Git translation processUp to the version 3.3.4 SubGit only used Git author name, so committer name did not mean much.
Since v.3.3.4 SubGit uses committer name for the author mapping by default. Since v.3.3.6 there's also an option to switch back to using author name for the mapping with the core.mapGitCommitter setting:
No Format |
---|
[core]
mapGitCommitter = true|false |
When it’s set to true (default), SubGit uses committer's name. Set it to false to make SubGit use author's name.
Info | ||
---|---|---|
| ||
Note, that SubGit uses authors names to count licensed users, see Licensing manual for details. |
Configuration options
Anchor | ||||
---|---|---|---|---|
|
All the configuration options reside in SubGit configuration file, that is situated in subgit subdirectory inside a newly created Git repository:
No Format |
---|
GIT_REPOS_PATH/subgit/config |
There are two configuration options that relate to authors:
core.authorsFile
Anchor core.authorsFile core.authorsFile 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 authors file is situated in SubGit directory:
No Format [core] authorsFile = subgit/authors.txt
There may be more that one
authorsFile
option set in the file:No Format [core] authorsFile = subgit/authors.txt authorsFile = /etc/authors.txt
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
johndoe
appears in both authors files:No Format subgit/authors.txt johndoe = John Doe <johndoe@example.com> … /etc/authors.txt johndoe = John M. Doe <john_doe@example.com>
In this case, the SVN name
johndoe
is being mapped to Git nameJohn Doe <johndoe@example.com>
as it appears first in the list.
core.defaultDomain
Anchor core.defaultDomain core.defaultDomain 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:
No Format Author: john_doe <>
Info | ||
---|---|---|
| ||
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 |
Automatic Authors Mapping Anchor AutoMapping AutoMapping
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@domain.com> is translated to Author Name in Subversion
defaultDomain here stands for the core.defaultDomain
SubGit configuration option.
During initial 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:
No Format |
---|
[core]
defaultDomain = example.com |
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:
No Format |
---|
Author: john_doe <john_doe@git.example.com> |
Similarly, Git commits that made by John Doe <johndoe@example.com> Git user appears in SVN with John Doe author name.
Authors File Anchor AuthorsFile AuthorsFile
The authors mapping file is a text file filled with SVN username - Git author pairs. Each pair maps SVN username to Git author like:
No Format |
---|
svn_user_name = Git Name <gitname@domain.name> |
For example, a mapping for a user John Doe may look like this:
No Format |
---|
john_doe = John Doe <john_doe@example.com> |
Each mapping pair must appear on a new line.
During SVN to Git translation, SubGit searches all specified authors files for a mapping pair. If the matching pair is found, SubGit uses appropriate author name. If there is no match, then SubGit generates author name according to automatic mapping rules.
It is possible to map more than one SVN username to the same Git author:
No Format |
---|
john_doe = John Doe <john_doe@example.com>
johndoe = John Doe <john_doe@example.com> |
Revisions that are created either by john_doe
or johndoe
are being translated to Git commits with author name John Doe <john_doe@example.com>
. However, Git commits that are made by John Doe <john_doe@example.com>
are being translated to SVN revision using first SVN username in authros files that matches particular Git name – john_doe
in this case.
Similarly, one SVN username can be mapped to different Git authors:
No Format |
---|
jdoe = John Doe <john_doe@example.com>
jdoe = Jane Doe <jane_doe@example.com>
jdoe = James Doe <james_doe@example.com> |
Again, every Git commit made by those authors will be translated with author set to jdoe.
SVN revisions made by jdoe
is always set to first matching Git user in the authors files
– John Doe <john_doe@example.com>
in this particular case.
Changes made to authors files are being applied immediately, there is no need to restart mirroring or reinstall SubGit.
Scriptable Authors Mapping
Anchor | ||||
---|---|---|---|---|
|
In addition to the authors files, there is another way to establish 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 send its work result to the standard output. Input and output data must fulfil the following formats:
for Git to Subversion mapping:
No Format INPUT: author Name author email OUTPUT: subversion_user_name
for Subversion to Git mapping:
No Format INPUT: subversion_user_name OUTPUT: author Name author email
Every time SubGit needs to map an author name, it invokes the authors helper, 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.
On configuration phase SubGit creates a simple authors.sh
script in samples
subdirectory. This script doesn't do much useful, it just demonstrates how input data is being read and output data provided.
Expand | ||
---|---|---|
| ||
|
For more details on the authors helper see Script-provided authors mapping article.