/ 
Git-Mailmap-0.005
River stage zero No dependents
/ Git::Mailmap

NAME

Git::Mailmap - Construct and read/write Git mailmap file.

VERSION

version 0.005

SYNOPSIS

require Git::Mailmap;

my $mailmap_file_as_string = '<cto@company.xx> <cto@coompany.xx>
Some Dude <some@dude.xx>         nick1 <bugs@company.xx>
Other Author <other@author.xx>   nick2 <bugs@company.xx>
';

my $plain_mailmap = Git::Mailmap->new(); # => isa 'Git::Mailmap'
$plain_mailmap->from_string('mailmap' => $mailmap_file_as_string);

# OR:

my $mailmap = Git::Mailmap->from_string('mailmap' => $mailmap_file_as_string); # => isa 'Git::Mailmap'
my $correct = $mailmap->verify( 'proper-email' => '<cto@company.xx>'); # => 1
my $fail = $mailmap->verify(
        'proper-email' => '<cto@company.xx>',
        'proper-name' => 'CTO'); # => 0
# Fail: no email address with that name!
my ($mapped_to_name, $mapped_to_email) = $mailmap->map(
        'email' => '<bugs@company.xx>',
        'name' => 'nick1');
# mapped_to_name => 'Some Dudeeed'
# mapped_to_email => '<some@dude.xx>'
my @mapped_to = $mailmap->map('email' => '<cto@coompany.xx>');
# mapped_to => is_deeply (undef, '<cto@company.xx>')

# Return map as string for writing to file.
my $map = $mailmap->to_string(); # => like qr/Some Dude/

DESCRIPTION

Git::Mailmap is a pure Perl implementation of the mailmap functionality in Git. It allows to create a mailmap by adding a mapped address at a time, or removing unwanted ones. You can also read or write the mailmap file as a string.

For mailmap, please see http://git-scm.com/docs/git-shortlog#_mapping_authors

STATUS

Package Git::Mailmap is currently being developed so changes in the API and functionality are possible, though not likely.

REQUIREMENTS

The Git::Mailmap package requires the following packages (in addition to normal Perl core packages):

Carp
Carp::Assert
Carp::Assert::More
Params::Validate
Readonly
Log::Any

SUBROUTINES/METHODS

new

Creator function.

map

Map the committer name and email to proper name/email. The email can be proper-email or committer-email (alias). Email is mandatory parameter. If also name is given, then looks for both. If only email, then the mapping is done to the first matching email address, regardless of the name.

Parameters:
name, not mandatory.
email, mandatory.
Return: LIST(proper-name, proper-email). If no name is mapped, then undef. If no email address is mapped, then both are undef.

add

Add new committer. Add all other information. Note!

  • There can be only one proper name for each proper email. If more is found, the latter replaces the former.

  • There can be several different commit names for each commit email.

Parameters:
proper-email, mandatory
proper-name, not mandatory
commit-email, not mandatory
commit-name, not mandatory
Return: [NONE]

verify

Search for a given name and/or email.

Parameters:
proper-email, not mandatory.
proper-name, not mandatory. If matching name is not important, don't set the *-name parameters!
commit-email, not mandatory.
commit-name, not mandatory.
Return: 1/0, 1 if verified to exist.

remove

Remove committer information. Remove as much information as you can.

Parameters:
proper-email, mandatory. If you specify only this, the whole entry (with proper-name and aliases) will be removed. Other combinations are not supported.
proper-name, not mandatory. Not supported.
commit-email, not mandatory. If you specify only this, every entry will be checked, and all aliases with this commit email will be removed. If you specify this together with proper-email, only the alias in the entry with that proper-email will be removed.
commit-name, not mandatory. Not supported.
all, not mandatory. Cannot be used together with other parameters. Removes all committers.
Return: [NONE]

from_string

Read the committers from a string. If any committers already exist, these will not be removed; so it is possible to merge mailmap files. If called as a class method (creator method instead of method new()), will also create the object and return it.

Parameters:
mailmap, mandatory. This is the mailmap file as a string.
Return: the object.

to_string

Return a mailmap file as string.

Parameters:
[NONE]
Return: string.

AUTHOR

'Mikko Koivunalho <mikko.koivunalho@iki.fi>'

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Mikko Koivunalho.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.