#!perl
use strict;
use OptArgs qw/dispatch/;

dispatch(qw/run App::githook_perltidy/);

1;
__END__

=head1 NAME

githook-perltidy - run perltidy and podtidy before Git commits

=head1 VERSION

0.11.1.

=head1 SYNOPSIS

Make sure everyone uses the same tidy options across your project:

    $ perltidy -b -w -dop | grep -v dump-options > .perltidyrc
    $ echo '--columns 72' > .podtidy-opts
    $ git add .perltidyrc .podtidy-opts
    $ git commit

Install the pre-commit and post-commit hooks:

    $ githook-perltidy install

=head1 DESCRIPTION

B<githook-perltidy> is a script that can be invoked by Git pre-commit
and post-commit hooks to run L<perltidy> and L<podtidy> on Perl and POD
files (and optionally run L<make>(1) targets), ensuring that your
project's code is always cleanly committed.

This script is is efficient: it only modifies Perl and POD files that
are being committed and not every file in your repository. It also
tries its hardest to be safe: the index and working tree are stashed
away beforehand, and restored in the event of failure.

There are three types of action this script will take as determed by
the first argument:

=over 4

=item install [--force, -f] [MAKE ARGS]

Should be run from the command-line in the top-level directory of your
repository. Writes F<pre-commit> and F<post-commit> files in the
F<$GIT_DIR/hooks/> directory. Any MAKE ARGS given will be added to the
C<githook-perltidy pre-commit> call.

This command will fail if there is no .perltidyrc file in the
repository or if the hooks directory isn't found. It will also fail if
either of the hook files already exist, unless C<--force> is used.

=item pre-commit [MAKE ARGS]

Called from a Git pre-commit hook.  Backs up your index and working
tree into a Git stash. Runs L<perltidy> on any Perl files in the Git
index using the F<.perltidyrc>. If F<.podtidy-opts> exists then
L<podtidy> will also be run on any POD files in the Git index,
otherwise a warning is issued.

If any MAKE ARGS are given they will be passed to a L<make> call.  This
way you can ensure that your code passes a C<make test> or C<make
disttest> check before each commit.  If the PERLTIDY_MAKE environment
variable exists it will I<override> any arguments. Setting
PERLTIDY_MAKE="" will skip the make call entirely.

Failure of any of the above will result in a hard reset and the saved
stash popped (I.e. re-applied and deleted). The commit will be stopped.
On success the index is updated with the tidied files and the commit is
allowed to proceed.  In the event that your index was an interactive or
patched version of your working tree, the stash will be kept for the
post-commit hook. Otherwise it will be dropped.

This command will fail if there is no .perltidyrc file in the
repository.

=item post-commit

Called from a Git post-commit hook to re-apply stashed (but not
indexed) changes. In the event that your index was an interactive or
patched version of your working tree, the post-commit command does the
following:

=over

=item * checks out the I<previous> commit

=item * pops the stash saved by the pre-commit command

=item * tidies the files that were stashed

=item * saves a new stash with the completely tidied files

=item * checks out the I<latest> commit

=item * pops the stash with the tidied files

=back

=back

=head1 CAVEATS

There are two ways in which B<githook-perltidy> behaviour may affect
your existing workflow. Firstly 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'.

Secondly, 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.

=head1 FILES

=over

=item F<.perltidyrc>

Perltidy command options file.

=item F<.podtidy-opts>

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

=item F<.githook-perltidy>

A temporary file used to communicate between the pre-commit and
post-commit calls.

=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-2012 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.

