view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        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.