/ 
Git-MoreHooks-0.013
River stage zero No dependents
/ Git::MoreHooks::CheckCommitAuthorFromMailmap

NAME

Git::MoreHooks::CheckCommitAuthorFromMailmap - Check Git commit author by using the mailmap file.

VERSION

version 0.013

SYNOPSIS

Use package via Git::Hooks interface (configuration in Git config file).

DESCRIPTION

By its very nature, the Git VCS (version control system) is open and with very little access control. It is common in many instances to run Git under one user id (often "git") and allowing access to it via SSH and public keys. This means that user can push commits without any control on either commit message or the commit author.

This plugin allows one to enforce policies on the author information in a commit. Author information consists of author name and author email. Email is the more important of these. In principle, email is used to identify committers, and in some Git clients, GitWeb WWW-interface, for instance, email is also used to show the Gravatar of the committer. The common way for user to set the author is to use the (normally global) configuration options user.name and user.email. When doing a commit, user can override these via the command line option --author.

STATUS

Package Git::MoreHooks is currently being developed so changes in the existing hooks are possible.

USAGE

To enable CheckCommitAuthorFromMailmap plugin, you need to add it to the githooks.plugin configuration option:

git config --add githooks.plugin Git::MoreHooks::CheckCommitAuthorFromMailmap

Git::MoreHooks::CheckCommitAuthorFromMailmap plugin hooks itself to the hooks below:

  • pre-commit

    This hook is invoked during the commit, to check if the commit author name and email address comply.

  • update

    This hook is invoked multiple times in the remote repository during git push, once per branch being updated, to check if the commit author name and email address of all commits being pushed comply.

  • pre-receive

    This hook is invoked once in the remote repository during git push, to check if the commit author name and email address of all commits being pushed comply.

  • ref-update

    This hook is invoked when a push request is received by Gerrit Code Review, to check if the commit author name and email address of all commits being pushed comply.

  • patchset-created

    This hook is invoked when a push request is received by Gerrit Code Review for a virtual branch (refs/for/*), to check if the commit author name and email address of all commits being pushed comply.

  • draft-published

    The draft-published hook is executed when the user publishes a draft change, making it visible to other users.

CONFIGURATION

This plugin is configured by the following git options.

githooks.checkcommitauthorfrommailmap.ref REFSPEC

By default, the message of every commit is checked. If you want to have them checked only for some refs (usually some branch under refs/heads/), you may specify them with one or more instances of this option.

The refs can be specified as a complete ref name (e.g. "refs/heads/master") or by a regular expression starting with a caret (^), which is kept as part of the regexp (e.g. "^refs/heads/(master|fix)").

githooks.checkcommitauthorfrommailmap.match-mailmap-name [01]

Match also with the mailmap name, not just with the email address. Default: 1 (on).

githooks.checkcommitauthorfrommailmap.allow-mailmap-aliases [01]

Allow matching also with mailmap alias (commit) email (and name if allowed), not just proper email (and name if allowed, see match-mailmap-name). Default: 1 (On).

Mailmap File

In mailmap file the author can be matched against both the proper name and email or the alias (commit) name and email. For mailmap contents, please see git-shortlog - MAPPING AUTHORS.

The mailmap file is located according to Git's normal preferences:

1 Default mailmap.

If exists, use file HEAD:.mailmap, located at the root of the repository.

2 Configuration variable mailmap.file.

The location of an augmenting mailmap file. The default mailmap is loaded first, then the mailmap file pointed to by this variable. The contents of this mailmap will take precedence over the default one's contents (when needed). File should, perhaps, be in UTF-8 format.

The location of the mailmap file may be in a repository subdirectory, or somewhere outside of the repository itself. If the repo is a bare repository, then this config option will raise an error. Use variable mailmap.blob if file is in the repository. If file cannot be found, this will raise an error.

3 Configuration variable mailmap.blob.

If the repo is a bare repository, and mailmap is in it, then this config variable should be used. It points to a Git blob in the bare repo. The contents of this mailmap will take precedence over the default one's contents (when needed) and the augmenting mailmap file's contents (var mailmap.file).

EXPORTS

This module exports the following routines that can be used directly without using all of Git::Hooks infrastructure.

check_commit_at_client GIT

This is the routine used to implement the pre-commit hook. It needs a Git::More object.

check_commit_at_server GIT, COMMIT

This is the routine used to implement the pre-commit hook. It needs a Git::More object and a commit hash from Git::More::get_commit().

check_affected_refs GIT

This is the routing used to implement the update and the pre-receive hooks. It needs a Git::More object.

check_patchset GIT, HASH

This is the routine used to implement the patchset-created Gerrit hook. It needs a Git::More object and the hash containing the arguments passed to the hook by Gerrit.

NOTES

Thanks go to Gustavo Leite de Mendonça Chaves for his Git::Hooks package.

BUGS AND LIMITATIONS

The hook reads the file HEAD:.mailmap with git command show. This is clearly the wrong approach for several reasons. Firstly, git-show is a porcelain command, not a plumbing command. Secondly, git-show fails with an error if there is no commits in the repository. Thirdly, git-show only shows committed files. In the pre-commit hook we want to read a file in the working directory.

AUTHOR

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

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 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.