NAME
    githook-perltidy - run perltidy and podtidy before Git commits

VERSION
    0.11.11_2 (2018-07-27)

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 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.

  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 Pod::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

   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. githook-perltidy does not depend on
    Perl::Tidy::Sweetened directly so you will want to add that 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.
    githook-perltidy does not depend on Perl::Critic directly so you will
    want to add that 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 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.

  githook-perltidy install [--force, -f]
    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.

        $ 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.

  githook-perltidy pre-commit
    The "pre-commit" command loops through the Git index, checking out files
    to a temporary working directory. For each temporary file it then:

    *   Runs perlcritic if it is a Perl file and .perlcriticrc exists.

    *   Runs perltidy if it is a Perl file, unless .perltidy-sweet exists in
        which case perltidy-sweet is run instead.

    *   Runs podtidy if it is a Perl or a Pod file and .podtidy-opts exists.

    *   Updates the Git index ("git add $TEMP_FILE")

    *   Runs perltidy and/or podtidy on your working tree file of the same
        name. This prevents future "git diff" calls from showing diffs where
        there won't actually be any.

    *   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.

    Any tidying or critique 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
    --verbose, -v
        Print underlying Git commands or filesystem actions as they are run.

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.

FILES
    .perltidyrc
        Perltidy command options file.

    .perltidyrc.sweetend
        Perltidier (Perl::Tidy::Sweetened) command options file. Conflicts
        with .perltidyrc.

    .podtidy-opts
        Podtidy command options file. This is githook-perltidy specific.

    .readme_from
        Automatic README config file. This is githook-perltidy specific.

ENVIRONMENT
    NO_GITHOOK_PERLTIDY
        Setting this to 1 makes githook-perltidy 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)

AUTHOR
    Mark Lawrence <nomad@null.net>

COPYRIGHT AND LICENSE
    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.

