NAME
githook-perltidy - run perltidy and podtidy before Git commits
VERSION
0.10.2.
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
DESCRIPTION
githook-perltidy is a script that can be invoked by Git pre-commit and
post-commit hooks to run perltidy and podtidy on Perl and POD files (and
optionally run 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:
install [MAKE ARGS]
Should be run from the command-line in the top-level directory of
your repository. Writes pre-commit and post-commit files in the
$GIT_DIR/hooks/ directory. Any MAKE ARGS given will be added to the
"githook-perltidy pre-commit" call.
This command will fail if there is no .perltidyrc file in the
repository, if the hooks directory isn't found, or if either of the
hook files already exist.
pre-commit [MAKE ARGS]
Called from a Git pre-commit hook. Backs up your index and working
tree into a Git stash. Runs perltidy on any Perl files in the Git
index using the .perltidyrc. If .podtidy-opts exists then 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 make call. This
way you can ensure that your code passes a "make test" or "make
disttest" check before each commit. If the PERLTIDY_MAKE environment
variable exists it will *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.
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:
* checks out the *previous* commit
* pops the stash saved by the pre-commit command
* tidies the files that were stashed
* saves a new stash with the completely tidied files
* checks out the *latest* commit
* pops the stash with the tidied files
CAVEATS
There are two ways in which 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.
FILES
.perltidyrc
Perltidy command options file.
.podtidy-opts
Podtidy command options file. This is githook-perltidy specific.
.githook-perltidy
A temporary file used to communicate between the pre-commit and
post-commit calls.
SUPPORT
This tool is managed via github:
https://github.com/mlawren/githook-perltidy
SEE ALSO
githooks(5), perltidy(1), podtidy(1)
AUTHOR
Mark Lawrence <nomad@null.net>
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.