NAME

Porting/updateAUTHORS.pl - Automatically update AUTHORS and .mailmap based on commit data.

SYNOPSIS

Porting/updateAUTHORS.pl

 Options:
   --help               brief help message
   --man                full documentation
   --authors-file=FILE  override default location of AUTHORS
   --mailmap-file=FILE  override default location of .mailmap

OPTIONS

--help

Print a brief help message and exits.

--man

Prints the manual page and exits.

--authors-file=FILE

--authors_file=FILE

Override the default location of the authors file, which is "AUTHORS" in the current directory.

--mailmap-file=FILE

--mailmap_file=FILE

Override the default location of the mailmap file, which is ".mailmap" in the current directory.

DESCRIPTION

This program will automatically manage updates to the AUTHORS file and .mailmap file based on the data in our commits and the data in the files themselves. It uses no other sources of data. Expects to be run from the root a git repo of perl.

In simple, execute the script and it will either die with a helpful message or it will update the files as necessary, possibly not at all if there is no need to do so. Note it will actually rewrite the files at least once, but it may not actually make any changes to their content. Thus to use the script is currently required that the files are modifiable.

Review the changes it makes to make sure they are sane. If they are commit. If they are not then update the AUTHORS or .mailmap files as is appropriate and run the tool again. Typically you shouldn't need to do either unless you are changing the default name or email for a user. For instance if a person currently listed in the AUTHORS file whishes to change their preferred name or email then change it in the AUTHORS file and run the script again. I am not sure when you might need to directly modify .mailmap, usually modifying the AUTHORS file should suffice.

FUNCTIONS

Note that the file can also be used as a package. If you require the file then you can access the functions located within the package Porting::updateAUTHORS. These are as follows:

add_new_mailmap_entries($mailmap_hash, $mailmap_info, $mailmap_file)

If any additions were identified while reading the commits this will inject them into the mailmap_hash so they can be written out. Returns a count of additions found.

check_fix_mailmap_hash($mailmap_hash, $authors_info)

Analyzes the data contained the in the .mailmap file and applies any automated fixes which are required and which it can automatically perform. Returns a hash of adjusted entries and a hash with additional metadata about the mailmap entries.

main()

This implements the command line version of this module, handle command line options, etc.

merge_mailmap_with_AUTHORS_and_checkAUTHORS_data

This is a utility function that combines data from this tool with data contained in Porting/checkAUTHORS.pl it is not used directly, but was used to cleanup and generate the current version of the .mailmap file.

parse_mailmap_hash($mailmap_hash)

Takes a mailmap_hash and parses it and returns it as an array of array records with the contents:

    [ $preferred_name, $preferred_email,
      $other_name, $other_email,
      $line_num ]

read_and_update($authors_file, $mailmap_file)

Wraps the other functions in this library and implements the logic and intent of this tool. Takes two arguments, the authors file name, and the mailmap file name. Returns nothing but may modify the AUTHORS file or the .mailmap file. Requires that both files are editable.

read_commit_log($authors_info, $mailmap_info)

Read the commit log and find any new names it contains.

read_authors($authors_file)

Read the AUTHORS file and return data about it.

read_mailmap($mailmap_file)

Read the .mailmap file and return data about it.

update_authors($authors_info, $authors_preamble, $authors_file)

Write out an updated AUTHORS file. This is done atomically using a rename, we will not leave a half modified file in the repo.

update_mailmap($mm_hash, $mm_preamble, $mailmap_file, $mm_info)

Write out an updated .mailmap file. This is done atomically using a rename, we will not leave a half modified file in the repo.

TODO

More documentation and testing.

SEE ALSO

Porting/checkAUTHORS.pl

AUTHOR

Yves Orton <demerphq@gmail.com>