=head1 USER TUTORIAL

As a git user you may be interested in enabling some hooks for your
local git repositories. In particular, you may be interested in
guaranteeing that the same policies that are being enforced by the
remote repositories you push to are enforced earlier when you commit
locally.

=head2 GIT::HOOKS DRIVER SCRIPT

Git::Hooks only need a single script to drive all hooks implemented by
yourself or by the plugins you enable. The script I use was created
like this:

    $ cat >~/bin/githooks.pl <<EOF
    #!/usr/bin/env perl
    
    BEGIN { $ENV{GITPERLLIB} = '/usr/share/perl5' };
    
    use Git::Hooks;
    
    run_hook($0, @ARGV);
    EOF
    
    $ chmod +x ~/bin/githooks.pl

Without the C<BEGIN> block I get the following error when I use it in
my Ubuntu notebook:

    $ ~/bin/githooks.pl
    Can't locate Git.pm in @INC (@INC contains: /opt/perl/perl5/perlbrew...
    BEGIN failed--compilation aborted at /opt/perl/perl5/perlbrew/.../Git/More.pm line 15.
    Compilation failed in require at /opt/perl/perl5/perlbrew/.../Git/Hooks.pm line 51.
    BEGIN failed--compilation aborted at /opt/perl/perl5/perlbrew/.../Git/Hooks.pm line 51.
    Compilation failed in require at /home/gustavo/bin/githooks.pl line 5.
    BEGIN failed--compilation aborted at /home/gustavo/bin/githooks.pl line 5.

This is because the C<Git.pm> module can't be found in my standard
@INC, since I'm using a L<perlbrew|http://perlbrew.pl/> installed
Perl. If you get the same error, you must define the environment
variable C<GITPERLLIB> in a BEGIN block before the C<use Git::Hooks>
line. In Debian/Ubuntu the module is installed as
</usr/share/perl5/Git.pm> as part of the C<git> package.

=head2 HOOK LINKS

In order to make it easy to setup your hooks, it's useful to create a
repository template for git to use when you perform a C<git init> or a
C<git clone>.

In Ubuntu, git's standard repository template resides in
C</usr/share/git-core/templates>. If you can't find it there, read the
C<TEMPLATE DIRECTORY> section of the C<git help init> manual to see
where is your git's default template directory.

You may customize one for you like this:

    $ cp -a /usr/share/git-core/templates ~/.git-templates
    $ cd ~/.git-templates/hooks
    $ rm *
    $ for i in commit-msg post-commit pre-commit pre-rebase
    > do ln -s ~/bin/githooks.pl $i
    > done

This copies the default template directory to C<~/.git-template> (you
may choose another directory), removes all sample hooks and creates
symbolic links to the Git::Hooks driver script which we created above
for four hooks: C<commit-msg>, C<post-commit>, C<pre-commit>,
C<pre-rebase>. These are all the hooks I'm interested in locally. Your
mileage may vary.

You must tell git to use your repository template instead of its
default. The best way to do it is to configure it globally like this:

    $ git config --global init.templatedir ~/.git-templates

Now, whenever you C<git init> or C<git clone> a new repository, it
will automatically be configured to use Git::Hooks.

=head2 CONFIGURATION

By default Git::Hooks does nothing. At the least, it must be
configured to enable some plugins and configure them to your
taste. You should read the plugins's documentation to understand them
and decide which ones you would like to enable globally and which ones
you would like to enable locally for particular repositories.

Here I show my personal preferences. You can take it as a baseline
from which you can make variations.

=head3 Global Configuration

This is what I have in my global git configuration (C<~/.gitconfig>):

    [githooks]
            plugin = CheckLog
            plugin = CheckRewrite
    [githooks "checkjira"]
            jiraurl  = https://jira.cpqd.com.br
            jirauser = gustavo
            jirapass = a-very-large-and-difficult-to-crack-password
            matchlog = (?s)^\\[([^]]+)\\]
    [githooks "checklog"]
            title-max-width = 62

The only plugins I want enabled for every repository are C<CheckLog>
and C<CheckRewrite>. The latter is simple, as it doesn't require any
configuration whatsoever. With it I feel more confident to perform
C<git commit --amend> and C<git rebase> commands knowing that I'm
going to be notified in case I'm doing anything dangerous.

The C<CheckLog> is also useful to guarantee that I'm not deviating
from the common git policies regarding the commit messages. The only
thing I change from the defaults is the C<title-max-width>, because I
think 50 characters is very constraining.

The section C<githooks "checkjira"> contains some global configuration
for the C<CheckJira> plugin, which I enable only for some
repositories. Since the C<CheckJira> plugin has to connect to our JIRA
server, it needs the server URL and some credentials to
authenticate. The C<matchlog> regex makes JIRA issue keys be looked
for only inside a pair of brackets at the beginning of the messages
title line.

=head3 Local Configuration

I enable other plugins for specific repositories, since they depend on
the context in which they are developed.

At L<CPqD|http://www.cpqd.com.br/> we use
L<JIRA|http://www.atlassian.com/software/jira> and
L<Gerrit|https://code.google.com/p/gerrit/> internally. So, for my
work-related repositories I have this in their C<.git/config>:

    [githooks]
            plugin = CheckJira
            plugin = GerritChangeId
    [githooks "checkjira"]
            project = CDS

C<GerritChangeId> doesn't require any configuration. It simply inserts
a C<Change-Id> line in the messages of all commits. These are required
by Gerrit.

I use C<CheckJira> to remind me to cite a JIRA issue in every commit
message. I make two deviations from its default configuration. The
C<project> value makes it accept only issues of the CDS JIRA project.

=cut
