NAME

perlcritic-checker.pl - Perl::Critic Subversion Hook

SYNOPSIS

perlcritic-checker.pl [options]

 Options:
   --revision|-r       Revision ID
   --transaction|-t    Transaction ID
   --repository|-p     Path to SVN repository
   --config|-c         Path to config file
   --help|-?           Show brief help message
   --man               Show full documentation
 

USAGE EXAMPLE

Put this into your Subversion's pre-commit hook:

/abs/path/to/perlcritic-checker.pl -p $REPOS -c /abs/path/to/perlcritic-checker.conf -t $TXN || exit 1

DESCRIPTION

perlcritic-checker is a subversion hook that allows commits to go through if and only if the code passes validation using Perl::Critic module. This way you can apply consistent coding practices inside your team.

Main features:

• you can specify different Perl::Critic's profiles for different paths in your repository

• you can bypass checks when you do need this

• you can apply the checker to your existing large legacy Perl project by using "progressive mode" feature: in progressive mode perlcritic-checker doesn't complain about existing violations but prevents introducing new ones

• perlcritic-checker comes with a test suite

CONFIGURATION FILE

Configuration file example follows. In fact, it's a ordinary Perl hash. You can check it using `perl -c' to avoid syntax errors.

 {
     # Progressive mode: {0|1}. In progressive mode perlcritic-checker
     # doesn't complains about existing violations but prevents
     # introducing new ones. Nice feature for applying Perl::Critic
     # to the existing projects gradually.
     progressive_mode => 1,
 
     # Emergency commits: {0|1}. There are situations when you *do* need
     # to commit changes bypassing all checks (e.g. emergency bug fixes).
     # This featue allows you bypass Perl::Critic using "magic" prefix in
     # comment message, e.g.: svn ci -m "NO CRITIC: I am in hurry" FooBar.pm
     allow_emergency_commits  => 1,
 
     # Magic prefix described above can be customized:
     emergency_comment_prefix => 'NO CRITIC',

     # Limit maximal number of reported violations. This parameter works
     # differently in strict and progressive modes. In strict mode it
     # will truncate long list of violations: only N most severe violations
     # will be shown. In progressive mode such behaviour has no sense,
     # that's why user will be asked to run perlcritic locally.
     #
     # In fact, this parameter is a workaround for a subtle bug in generic
     # svn-client that happens when svn hook (i.e. perlcritic-checker.pl)
     # outputs too much data: svn-client just reports "Connection closed
     # unexpectedly". In order to reproduce this bug several additional
     # conditions should be met:
     # - repository access scheme: 'svn://' (svnserve daemon)
     # - client and server on different machines
     # - svn-client and -server are running on linux
     # 
     # If you face the same problem, try to use the option below.
     #max_violations => 50,
 
     # SVN repository path -- to -- Perl::Critic's profile mapping.
     #
     # This feature allows you to apply different Perl::Critic's
     # policies for different paths in the repository. For example,
     # you can be very strict with brand-new projects, make an
     # indulgence for some existing project and completely disable
     # checking of auto-generated or third-party code.
     #
     # Each modified (added, updated, copied, moved) file name in the
     # repository is matched against a sequence of patterns below.
     # Keep in mind, *last* matching rule - wins.
     #
     # Profile paths can be either absolute or relative. In the later
     # case they will be mapped under $REPOS/hooks/perlcritic.d directory.
     profiles => [
         # Apply default profile for all Perl-code under 'project_name/trunk'
         {
             pattern => qr{project_name/trunk/.*?[.](pm|pl|t)$},
             profile => 'default-profile.conf',
         },
 
         # Disable checking of autogenerated Perl-code
         {
             pattern => qr{autogenerated-script[.]pl$},
             profile => undef,
         },
     ],
 }

Format of Perl::Critic's profiles is described in perlcritic(1p). Here is an example:

 # Make perlcritic very exacting
 severity = brutal
 
 # You can choose any level from 1 to 11, but 8 is recommended
 verbose = 8
 
 # Colorize violations depending on their severity level
 color = 1
 
 # Halt if this file contains errors
 profile-strictness = fatal
 
 # Ask perlcritic for a little indulgence
 exclude = Documentation
 
 # Explicitly set full path to Perl::Tidy's config
 [CodeLayout::RequireTidyCode]
 perltidyrc = /etc/perltidyrc

EXIT STATUS

0 - No code violations found, allow commit

1 - Code violations have been found, deny commit

255 - Error has occured, deny commit

SEE ALSO

http://perlcritic.com

AUTHOR

Alexander Simakov, <xdr (dot) box (at) Google Mail>

http://alexander-simakov.blogspot.com/

http://code.google.com/p/perlcritic-checker

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.