NAME
githook-perltidy - run perltidy before Git commits
VERSION
1.0.1_1 (yyyy-mm-dd)
SYNOPSIS
githook-perltidy COMMAND [OPTIONS...]
DESCRIPTION
githook-perltidy is a script designed to run from a Git pre-commit
hook. It ensures that your Perl files are always cleanly commited
with Perl::Tidy (or Perl::Tidy::Sweetened). The script can also call
Perl::Critic and 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.
Repository Setup
Before you can use githook-perltidy you need to make sure everyone
working on your code uses the the same Perl::Tidy and (probably)
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 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.
# For example in your cpanfile:
on develop => sub {
requires 'App::githook::perltidy' => 0;
};
Sweeter Tidying
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.
Critical Checks
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.
README from POD
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.
githook-perltidy install [--force, -f] [--absolute, -a]
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
if [ "$NO_GITHOOK_PERLTIDY" != "1" ]; then
PERL5LIB="" githook-perltidy pre-commit
fi
The install 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 file
already exists, unless "--force" is used to replace it.
By default the hook finds githook-perltidy via $PATH. If regular
changes to your PATH (e.g. due to perlbrew, local::lib, etc) break
that, you *may* wish to do an "--absolute" install instead to use
the full path. However, be aware that upgrading your system perl
and/or githook-perltidy might invalidate that, requiring you to
reinstall the hook to make it work again. Ideally you would install
githook-perltidy in a system-wide location (e.g. /usr/local/bin)
that doesn't change and does not depend on particular PERL5LIB.
githook-perltidy pre-commit
The "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 perltidy (or perltidy-sweet) (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.
* Runs perltidy and/or podtidy on your working tree file. This
prevents "git diff" from displaying an eroneous diff.
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.
GLOBAL OPTIONS
--help, -h
Print the full usage message and exit.
--verbose, -v
Print underlying Git commands or filesystem actions as they are
run.
--version, -V
Print the version and exit.
CAVEATS
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.
Previous versions of githook-perltidy made use of a Git post-commit
hook. If that hook is still in place you will receive an usage error
message after you commit. The post-commit call to githook-perltidy
(or possibly even the entire hook) can be removed.
FILES
.perltidyrc
Perl::Tidy options file.
.perltidyrc.sweetened
Perl::Tidy::Sweetened options file. Conflicts with .perltidyrc.
.podtidy-opts
Pod::Tidy options file. This is githook-perltidy specific.
.perlcriticrc
Perl::Critic options file.
.readme_from
Contains name of POD file to convert to a text README file. This
is githook-perltidy specific.
ENVIRONMENT
NO_GITHOOK_PERLTIDY
Setting this to 1 makes the "githook-perltidy pre-commit"
command a no-op. Useful if you want to make a non-tidy commit.
SUPPORT
This tool is managed via github:
https://github.com/mlawren/githook-perltidy
SEE ALSO
githooks(5), perltidy(1), podtidy(1), perlcritic(1)
AUTHOR
Mark Lawrence <nomad@null.net>
COPYRIGHT AND LICENSE
Copyright 2011-2022 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.