NAME

Git::MoreHooks::CheckPerl - Check committed files for Perl::Critic correctness.

VERSION

version 0.016

SYNOPSIS

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

DESCRIPTION

This plugin allows user to check committed Perl files with different static analysis tools for Perl source code. Currently supported is only Perl::Critic. Future support is planned for B::Lint and running syntax check command perl -c.

There are other ways to run Perl::Critic, such as simply running the executable perlcritic. This hook runs Perl::Critic within the same Git::Hooks process and therefore uses the same Perl installation and its modules. It saves you from starting a new process for every file you check, and you can install the policies together with everything else Git::Hooks needs.

In the case of server side repo, this hook takes content of the new or modified files directly from Git and passes them to Perl::Critic without writing them to a temporary dir only for perlcritic to read them again.

STATUS

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

USAGE

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

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

This plugin hooks itself to the following hooks:

• pre-commit

  This hook is invoked during the commit.

• pre-applypatch

  This hook is invoked during the email-based workflow after a patch is applied but before a commit is made.

• commit-received

  This hook is invoked when a commit is received by Gerrit either by direct push or by push for review (to refs/for/branch). It allows a push to be rejected before a review is created, or before the branch is updated in case of a direct push. It is called once for each commit in the push.

• pre-receive

  This hook is invoked once in the remote repository during git push.

• ref-update

  This hook is invoked when a push request is received by Gerrit Code Review.

• submit

  This is called when a user attempts to submit a change in Gerrit. It allows the submit to be rejected.

• update

  This hook is invoked multiple times in the remote repository during git push, once per branch being updated.

• draft-published

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

• patchset-created

  The patchset-created hook is executed asynchronously when a user performs a push to one of Gerrit's virtual branches (refs/for/*) in order to record a new review request.

Additional Dependencies

You need to install separately the dependencies needed for using different checkers.

Perl::Critic

Perl::Critic

CONFIGURATION

This plugin is configured by the following git options.

githooks.checkperl.use-temp-files BOOL

Whenever a checker supports it, files are not written to a temporary folder for checking. Instead they are extracted from Git and fed directly as scalar variables to a checker tool. If you want the checkers to read a file instead, set this config item to "1". Default is "0".

N.B. This config option is not yet implemented!

githooks.checkperl.name PATTERN

Use regexp or glob values to specify file patterns. This item uses same pattern as Git::Hooks::CheckFile config item name, but without the command.

Only the file's basename is matched against PATTERN. (Paths are not supported.) You can set name one or more times.

PATTERN is usually expressed with globbing to match files based on their extensions, for example:

    [githooks "checkperl"]
        name = *.pl

If you need more power than globs can provide you can match using regular expressions, using the qr// operator, for example:

    [githooks "checkperl"]
        name = qr/xpto-\\d+.pl/

Default values are:

    [githooks "checkperl"]
        name = *.p[lm]
        name = *.psgi
        name = *.t

githooks.checkperl.critic.active BOOL

Activate or deactivate Perl::Critic check. Set this to false ("0") if you only want to use the other checkers. Default is true ("1").

githooks.checkperl.critic.profile REF_AND_FILENAME

If you have committed a Perl::Critic configuration file (profile) to the repo, you can specify here where it is. There is no default value. The value must have the following pattern: "<ref name>:<file name>". E.g.

    [githooks "checkperl.critic"]
        profile = refs/heads/master:.perlcriticrc

It is not possible for this hook to simply use the current .perlcriticrc file in the repo and the currently active branch for security reasons.

If this item is not set, Perl::Critic is started with its own default values. It will not read the currently present .perlcriticrc file even if available.

githooks.checkperl.critic.cfg HASH

You can alternatively set all the values in the configuration but if profile is set, they are ignored.

Please consult to Perl::Critic for further information.

All the values in this section will be used when providing the configuration to Perl::Critic, including properties which Perl::Critic does not use but which are used to configure individual policies.

E.g.

    [githooks "checkperl.critic.cfg"]
        severity     = brutal
        verbose      = 11
        allow-unsafe = 0

N.B. This config option is not yet implemented!

EXPORTS

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

check_commit GIT

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

check_affected_refs GIT, REF

This is the routing used to implement the update and the pre-receive hooks. It needs a Git::More object and the name of the reference affected by the current push command.

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.

SEE ALSO

Git::Hooks

Perl::Critic

Alternative way to use Perl::Critic with Git::Hooks package: Git::Hooks::CheckFile.

NOTES

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

SUBROUTINES/METHODS

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.

cpanm Git::MoreHooks

perl -MCPAN -e shell
install Git::MoreHooks