#!perl
use strict;
use App::githook_perltidy;
use OptArgs2 qw/class_optargs/;

my ( $class, $opts ) = class_optargs('App::githook_perltidy');
eval "require $class" or die $@;
$class->new($opts)->run;

1;
__END__

=head1 NAME

githook-perltidy - run perltidy and podtidy before Git commits

=head1 VERSION

0.11.11_1 (2018-07-17)

=head1 SYNOPSIS

    githook-perltidy COMMAND [OPTIONS...]

=head1 DESCRIPTION

B<githook-perltidy> is a script designed to run from a Git pre-commit
hook. It ensures that your Perl and POD files are always cleanly
commited by running L<perltidy> (L<Perl::Tidy>) and L<podtidy>
(L<Pod::Tidy>) on them.

This script is is efficient: it only modifies files that are being
committed and not every file in your repository. It also tries its
hardest to be safe: tidying is performed in a temporary location so
that your own working files are not left in a bad state in the event of
failure.

Before you can use B<githook-perltidy> you need to make sure everyone
working on your code uses the the same tidy options:

    $ perltidy -b -w -dop | grep -v dump-options > .perltidyrc
    $ echo '--columns 72' > .podtidy-opts
    $ echo '^\.perltidyrc' >> MANIFEST.SKIP
    $ echo '^\.podtidy-ops' >> MANIFEST.SKIP
    $ git add .perltidyrc .podtidy-opts MANIFEST.SKIP
    $ git commit -m 'githook-perltidy support' && git push

You may prefer to tidy with L<Perl::Tidy::Sweetend> instead of plain
L<Perl::Tidy>. To enable that you use F<.perltidyrc.sweetened> instead
of F<.perltidyrc>. B<githook-perltidy> does not depend on
L<Perl::Tidy::Sweetend> directly so you will want to add that as an
explicit "develop" dependency in your F<cpanfile>, F<Makefile.PL> or
F<Build.PL>.

B<githook-perltidy> has an automatic README-from-POD feature. To enable
it you create and commit a file called F<.readme_from> containing the
name of a source file containing POD text:

    $ echo 'lib/Your/App.pm' > .readme_from
    $ echo '^\.readme_from' >> MANIFEST.SKIP
    $ git add .readme_from MANIFEST.SKIP
    $ git commit -m 'githook-perltidy readme_from' && git push

With the above in place the F<README> file will be updated (and
potentially committed) whenever F<lib/Your/App.pm> is committed.

=head2 githook-perltidy install [--force, -f]

Anyone making commits in a setup repository should ensure
B<githook-perltidy> runs from their pre-commit script. The C<install>
command can be used to create one, and must be run from the top-level
directory of your repository. It writes a F<pre-commit> file in the
F<$GIT_DIR/hooks/> directory.

    $ githook-perltidy install
    $ cat .git/hooks/pre-commit
    #!/bin/sh
    /usr/local/bin/githook-perltidy pre-commit

This command fails if there is no F<.perltidyrc> or
F<.perltidyrc.sweetened> file in the repository or if the hooks
directory isn't found. It will also fail if the Git F<pre-commit>
already file exists, unless C<--force> is used.

=head2 githook-perltidy pre-commit

The C<pre-commit> command loops through the Git index, checking out
Perl/POD files to a temporary working directory. It runs L<perltidy> on
the temporary Perl files using F<.perltidyrc> or
F<.perltidyrc.sweetened>. If F<.podtidy-opts> exists then L<podtidy> is
also run on Perl and POD files.  The Git index is updated along with
your original working files.

A tidying error stops the script (and therefore the commit)
immediately. Any successful cleanups to the index and working tree up
until that point remain in place.

This command fails if there is no F<.perltidyrc> or
F<.perltidyrc.sweetened> file in the repository.

If F<.readme_from> exists and the file named therein is tidied, then
B<githook-perltidy> translates it with L<Pod::Text> into a new README
file. If the README file is tracked by Git then it is also added it to
the index for committing.

=head1 GLOBAL OPTIONS

=over

=item --verbose, -v

Print underlying Git commands or filesystem actions as they are run.

=back

=head1 CAVEATS

There are two ways in which B<githook-perltidy> behaviour may affect
your existing workflow.

=over

=item * If you are accustomed to commiting
changes to files which are still open in your editor, your editor may
complain that the underlying file has changed on disk. Possibily your
editor doesn't even detect the change and your next write will not be
'tidy'.

=item * Aborting a commit with an empty commit message or via a later
command in the pre-commit hook will still result in changed (tidied)
files on disk and in the index.

=back

=head1 FILES

=over

=item F<.perltidyrc>

Perltidy command options file.

=item F<.perltidyrc.sweetend>

Perltidier (L<Perl::Tidy::Sweetened>) command options file. Conflicts
with F<.perltidyrc>.

=item F<.podtidy-opts>

Podtidy command options file. This is githook-perltidy specific.

=item F<.readme_from>

Automatic README config file. This is githook-perltidy specific.

=back

=head1 SUPPORT

This tool is managed via github:

    https://github.com/mlawren/githook-perltidy

=head1 SEE ALSO

L<githooks>(5), L<perltidy>(1), L<podtidy>(1)

=head1 AUTHOR

Mark Lawrence E<lt>nomad@null.netE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2011-2018 Mark Lawrence <nomad@null.net>

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 3 of the License, or (at your
option) any later version.

