githook-perltidy - run perltidy and podtidy before Git commits
0.11.11_1 (2018-07-17)
githook-perltidy COMMAND [OPTIONS...]
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 perltidy (Perl::Tidy) and podtidy (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 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 Perl::Tidy::Sweetend instead of plain Perl::Tidy. To enable that you use .perltidyrc.sweetened instead of .perltidyrc. githook-perltidy does not depend on Perl::Tidy::Sweetend directly so you will want to add that as an explicit "develop" dependency in your cpanfile, Makefile.PL or Build.PL.
githook-perltidy has an automatic README-from-POD feature. To enable it you create and commit a file called .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 README file will be updated (and potentially committed) whenever lib/Your/App.pm is committed.
Anyone making commits in a setup repository should ensure githook-perltidy runs from their pre-commit script. The install command can be used to create one, and must be run from the top-level directory of your repository. It writes a pre-commit file in the $GIT_DIR/hooks/ directory.
install
$ githook-perltidy install $ cat .git/hooks/pre-commit #!/bin/sh /usr/local/bin/githook-perltidy pre-commit
This command fails if there is no .perltidyrc or .perltidyrc.sweetened file in the repository or if the hooks directory isn't found. It will also fail if the Git pre-commit already file exists, unless --force is used.
--force
The pre-commit command loops through the Git index, checking out Perl/POD files to a temporary working directory. It runs perltidy on the temporary Perl files using .perltidyrc or .perltidyrc.sweetened. If .podtidy-opts exists then podtidy is also run on Perl and POD files. The Git index is updated along with your original working files.
pre-commit
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 .perltidyrc or .perltidyrc.sweetened file in the repository.
If .readme_from exists and the file named therein is tidied, then githook-perltidy translates it with 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.
Print underlying Git commands or filesystem actions as they are run.
There are two ways in which githook-perltidy behaviour may affect your existing workflow.
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'.
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.
Perltidy command options file.
Perltidier (Perl::Tidy::Sweetened) command options file. Conflicts with .perltidyrc.
Podtidy command options file. This is githook-perltidy specific.
Automatic README config file. This is githook-perltidy specific.
This tool is managed via github:
https://github.com/mlawren/githook-perltidy
githooks(5), perltidy(1), podtidy(1)
Mark Lawrence <nomad@null.net>
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.
To install App::githook_perltidy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::githook_perltidy
CPAN shell
perl -MCPAN -e shell install App::githook_perltidy
For more information on module installation, please visit the detailed CPAN module installation guide.