- GLOBAL OPTIONS
- SEE ALSO
- COPYRIGHT AND LICENSE
githook-perltidy - run perltidy and podtidy before Git commits
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 Perl::Tidy, and optionally Pod::Tidy and Perl::Critic 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.
$ 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 should also add App::githook::perltidy as an explicit "develop" dependency in your cpanfile, Makefile.PL or Build.PL, so that githook-perltidy gets installed when developers install the rest of your project's dependencies.
You may prefer to tidy with Perl::Tidy::Sweetened instead of plain Perl::Tidy. To enable that you commit a .perltidyrc.sweetened file instead of .perltidyrc. If you use this feature you will want to add Perl::Tidy::Sweetened as an explicit "develop" dependency in your cpanfile, Makefile.PL or Build.PL.
You may additionally wish to have Perl::Critic run against your commits. To enable that you simply commit a .perlcriticrc file to the repository. If you use this feature you will want to add Perl::Critic as an explicit "develop" dependency in your cpanfile, Makefile.PL or Build.PL.
githook-perltidy also has an automatic README-from-POD feature. To enable it you create and commit a file called .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 README file will be updated (and potentially committed) whenever lib/Your/App.pm is committed.
Anyone making commits in your repository should ensure that githook-perltidy runs before the Git commit completes. The
install command is used to create a pre-commit file in the $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 /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 to replace it.
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:
Runs perlcritic if .perlcriticrc exists (for a Perl file)
Runs podtidy if .podtidy-opts exists (for a Perl or Pod file)
Updates the Git index with the tidied file.
Creates a new README file using Pod::Text if the tidied file matches .readme_from. The README file gets committed if it is already being tracked by Git.
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.
This command fails if there is no .perltidyrc or .perltidyrc.sweetened file in the repository.
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.
Perl::Tidy options file.
Perl::Tidy::Sweetened options file. Conflicts with .perltidyrc.
Pod::Tidy options file. This is githook-perltidy specific.
Perl::Critic options file.
Contains name of POD file to convert to a text README file. This is githook-perltidy specific.
Setting this to 1 makes githook-perltidy a no-op. Useful if you want to make a non-tidy commit.
This tool is managed via github:
Mark Lawrence <email@example.com>
Copyright 2011-2018 Mark Lawrence <firstname.lastname@example.org>
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.