view release on metacpan or  search on metacpan

bin/githook-perltidy  view on Meta::CPAN

hook. It ensures that your Perl files are always cleanly commited with
L<Perl::Tidy> (or L<Perl::Tidy::Sweetened>). The script can also call
L<Perl::Critic> and L<Pod::Tidy> if you want.

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.

=head2 Repository Setup

Before you can use B<githook-perltidy> you need to make sure everyone
working on your code uses the the same L<Perl::Tidy> and (probably)
L<Pod::Tidy> options:

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

You should also add L<App::githook::perltidy> as an explicit "develop"
dependency in your F<cpanfile>, F<Makefile.PL> or F<Build.PL>, so that
B<githook-perltidy> gets installed when developers install the rest of
your project's dependencies.

	# For example in your cpanfile:
	on develop => sub {
		requires 'App::githook::perltidy' => 0;
	};

=head3 Sweeter Tidying

You may prefer to tidy with L<Perl::Tidy::Sweetened> instead of plain
L<Perl::Tidy>. To enable that you commit a F<.perltidyrc.sweetened>
file instead of F<.perltidyrc>.  If you use this feature you will want
to add L<Perl::Tidy::Sweetened> as an explicit "develop" dependency in
your F<cpanfile>, F<Makefile.PL> or F<Build.PL>.

=head3 Critical Checks

You may additionally wish to have L<Perl::Critic> run against your
commits.  To enable that you simply commit a F<.perlcriticrc> file to
the repository. If you use this feature you will want to add
L<Perl::Critic> as an explicit "develop" dependency in your
F<cpanfile>, F<Makefile.PL> or F<Build.PL>.

=head3 README from POD

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

    $ 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] [--absolute, -a]

Anyone making commits in your repository should ensure that
B<githook-perltidy> runs before the Git commit completes.  The
C<install> command is used to create a F<pre-commit> file in the
F<$GIT_DIR/hooks/> directory. It must be run from the top-level
directory of your repository.

    $ githook-perltidy install
    $ cat .git/hooks/pre-commit
	#!/bin/sh
	if [ "$NO_GITHOOK_PERLTIDY" != "1" ]; then
		PERL5LIB="" githook-perltidy pre-commit
	fi

The install 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> file
already exists, unless C<--force> is used to replace it.

By default the hook finds B<githook-perltidy> via C<$PATH>. If regular
changes to your PATH (e.g. due to perlbrew, local::lib, etc) break
that, you I<may> wish to do an C<--absolute> install instead to use the
full path. However, be aware that upgrading your system perl and/or
B<githook-perltidy> might invalidate that, requiring you to reinstall
the hook to make it work again. Ideally you would install
B<githook-perltidy> in a system-wide location (e.g. /usr/local/bin)
that doesn't change and does not depend on particular PERL5LIB.

=head2 githook-perltidy pre-commit

The C<pre-commit> command loops through the Git index, checking out
files to a temporary working directory. Then on each file that looks
like a Perl or Pod file it:

=over

=item * Runs L<perlcritic> if F<.perlcriticrc> exists (for a Perl file)

=item * Runs L<perltidy> (or L<perltidy-sweet>) (for a Perl file)

=item * Runs L<podtidy> if F<.podtidy-opts> exists (for a Perl or Pod file)

=item * Updates the Git index with the tidied file.

=item * Creates a new F<README> file using L<Pod::Text> if the tidied
file matches F<.readme_from>. The F<README> file gets committed if it
is already being tracked by Git.

=item * Runs L<perltidy> and/or L<podtidy> on your working
tree file. This prevents C<git diff> from displaying an eroneous diff.

=back

Any 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.