NAME

githook-perltidy - run perltidy and podtidy before Git commits

VERSION

0.9.2.

SYNOPSIS

Make sure everyone uses the same perltidy options across your project:

    $ perltidy -b -w -dop | grep -v dump-options > .perltidyrc
    $ git add .perltidyrc
    $ 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 and podtidy on any Perl or POD files in the Git index.

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

The temporary file .githook-perltidy is 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.