The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Git-Hooks-0.046
River stage one • 5 direct dependents • 5 total dependents
12 ++
/ TUTORIAL

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, so that you can avoid an onerous round trip to the common repository.

GIT::HOOKS DRIVER SCRIPT

Git::Hooks only need a single script to drive all hooks implemented by yourself or by the plugins you enable. If you do not need to create your own hooks, but want to use just the ones that come with Git::Hooks plugins, you can use a shared script like this for all your local repositories:

    #!/usr/bin/env perl
    use Git::Hooks;
    run_hook($0, @ARGV);

I save this script as ~/bin/githooks.pl under my $HOME directory. Do not forget to make it executable! If you invoke it directly it should do nothing but to exit normally:

    $ ~/bin/githooks.pl
    $ echo $?
    0

The GITPERLLIB environment variable

Git::Hooks uses the Git module which is part of the git installation and not at CPAN yet. So, depending on your environment, your Perl may not find it on its standard library directories. In this case, you'll get an error like this when you try to invoke the script:

    $ ~/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 Git.pm module can't be found in my standard @INC, since I'm using a perlbrew installed Perl. If you get the same error, define the environment variable GITPERLLIB in a BEGIN block before the use Git::Hooks line in the script. In Debian/Ubuntu the module is installed as </usr/share/perl5/Git.pm> as part of the git package. So, the script would be this:

    #!/usr/bin/env perl
    BEGIN { $ENV{GITPERLLIB} = '/usr/share/perl5' };
    use Git::Hooks;
    run_hook($0, @ARGV);

Now you simply need to create symbolic links under the .git/hooks directory of your repositories pointing to the common script. So, for example, if you want to enable some pre-commit and some commit-msg hooks, you would do this:

    $ cd .../.git/hooks
    $ ln -s ~/bin/githooks.pl pre-commit
    $ ln -s ~/bin/githooks.pl commit-msg

However, doing it manually for every repository is cumbersome and prone to mistakes and neglect. Fortunately, there is a better way. 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 git init or a git clone.

In Ubuntu, git's standard repository template resides in /usr/share/git-core/templates. If you can't find it there, read the TEMPLATE DIRECTORY section of the 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

These commands copy the default template directory to ~/.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: commit-msg, post-commit, pre-commit, and 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 git init or git clone a new repository, it will automatically be configured to use Git::Hooks.

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 are encouraged to make your own variations.

Global Configuration

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

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

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

The 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 title-max-width, because I think 50 characters is very constraining.

I disable the githooks.abort-commit option so that pre-commit and commit-msg hooks don't abort the commit in case of errors. That's because I find it easier to amend the commit than to remember to recover my carefully crafted commit message from the .git/COMMIT_EDITMSG afterwards.

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

Local Configuration

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

At CPqD we use JIRA and Gerrit internally. So, for my work-related repositories I have this in their .git/config:

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

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

I use CheckJira to remind me to cite a JIRA issue in every commit message. The project value makes it accept only issues of the CDS JIRA project for this particular repository.