NAME

Git::Hooks::CheckStructure - Git::Hooks plugin for ref/file structure validation.

VERSION

version 0.038

DESCRIPTION

This Git::Hooks plugin hooks itself to the hooks below to check if the files and references (branches and tags) added to the repository are allowed by their structure specification. If they don't, the commit/push is aborted.

• pre-commit

  This hook is invoked once in the local repository during a git commit. It checks if files being added comply with the file structure definition.

• update

  This hook is invoked multiple times in the remote repository during git push, once per branch being updated, checking if the references and files being added to the repository comply with its structure definition.

• pre-receive

  This hook is invoked once in the remote repository during git push, checking if the references and files being added to the repository comply with its structure definition.

To enable it you should add it to the githooks.plugin configuration option:

    git config --add githooks.plugin CheckStructure

NAME

CheckStructure - Git::Hooks plugin for ref/file structure validation.

CONFIGURATION

The plugin is configured by the following git options.

githooks.checkstructure.file STRUCTURE

This directive specifies the repository file structure, causing the push to abort if it adds any file that does not comply.

The STRUCTURE argument must be a Perl data structure specifying the file structure recursively as follows.

• ARRAY REF

  An array ref specifies the contents of a directory. The referenced array must contain a pair number of elements. Each pair consists of a NAME_DEF and a STRUCTURE. The NAME_DEF specifies the name of the component contained in the directory and the STRUCTURE specifies recursively what it must be.

  The NAME_DEF specifies a name in one of these ways:

  • STRING

    A string specifies the component name literally.

  • qr/REGEXP/

    A regexp specifies the class of names that match it.

  • NUMBER

    A number may be used as an else-clause. A positive number means that any name not yet matched by the previous NAME DEFs must conform to the associated STRUCTURE.

    A negative number means that no name will do and signals an error. In this case, if the STRUCTURE is a string it is used as a help message which is sent back to the user.

  If no NAME_DEF matches the component being looked for, then it is a structure violation and the hook fails.

• STRING

  A string must be one of 'FILE' and 'DIR', specifying what the component must be a file or a directory, respectively.

• NUMBER

  A positive number simply tells that the component can be anything: file or directory.

  A negative number tells that any component is a structure violation and the hook fails.

You can specify the githooks.checkstructure.file structure using either an eval: or a file: prefixed value, because they have to be evaluated as Perl expressions. The later is probably more convenient for most cases.

Let's see an example to make things clearer. Suppose the code below is in a file called hooks/file-structure.def under the repository directory.

        my $perl_standard_files = qr/^(Changes|dist\.ini|Makefile.PL|README)$/;

        [
            '.gitignore'         => 'FILE',
            $perl_standard_files => 'FILE',
            lib                  => [
                qr/\.pm$/        => 'FILE',
                1                => 'DIR',
            ],
            't'                  => [
                qr/\.t$/         => 'FILE',
            ],
        ];

Note that the last expression in the file is an array ref which specifies the repository file structure. It has four name/value pairs. The first one admits a file called literally .gitignore at the repository's root. The second admits a bunch of files commonly present in Perl module distributions, which names are specified by means of a regular expression. The third specifies that there might be a directory called lib at the repository's root, which may contain only .pm files and sub-directories under it. The fourth specifies that there might be a t directory, under which only <.t> files are admitted. No other file or directory is admitted at the repository's root.

In order to make the plugin read the specification from the file, configure it like this:

    git config githooks.checkstructure.file file:hooks/file-structure.def

githooks.checkstructure.ref STRUCTURE

This directive specifies the repository ref structure, causing the push to abort if it adds any reference (branch, tag, etc.) that does not comply.

The STRUCTURE argument must be a Perl data structure specifying the ref structure recursively in exactly the same way as was explained for the githooks.checkstructure.file variable above. Consider that reference names always begin with refs/. Branches are kept under refs/heads/, tags under refs/tags, remotes under refs/remotes, Gerrit branches under refs/for, and so on.

Let's see an example to make things clearer. Suppose the code below is in a file called hooks/ref-structure.def under the repository directory.

    my $version = qr/\d+\.\d+\.\d+(?:-[a-z_]+(?:\.\d+)?)?/;

    [
        refs => [
            heads => [
                qr/feature-.*/ => 'FILE',
                qr/release-.*/ => 'FILE',
                dev            => 'DIR',
            ],
            tags  => [
                qr/^v${version}$/ => 'FILE',
                qr/^build-\d+$/   => 'FILE',
            ],
        ],
    ];

The last expression in the file is an array ref which specifies the reference structure. In this case, it is very strict about which names are allowed for branches and tags. Branch names must begin with feature- or release-. The refs/heads/dev/ "directory" is probably a place for developers to create personal branches freely. There can be two kinds of tag names. The first one is for version tags and the second for tags generated by the build system.

Note that the plugin only checks references created during a push command. You don't need to explicitly allow for the master branch, because it is created during the init command. You also don't have to be concerned with the refs/remotes references, because they aren't used in the remote repository of a push.

In order to make the plugin read the specification from the file, configure it like this:

    git config githooks.checkstructure.ref file:hooks/ref-structure.def

EXPORTS

This module exports two routines that can be used directly without using all of Git::Hooks infrastructure.

check_affected_refs GIT

This is the routine used to implement the update and the pre-receive hooks. It needs a Git::More object.

check_commit GIT

This is the routine used to implement the pre-commit. It needs a Git::More object.

check_structure STRUCTURE, PATH

This is the main routine of the hook. It gets (usually) an array-ref specifying the repository STRUCTURE and a PATH to check against it. It returns a tuple, the first value of which is a boolean telling if the check was successful or not. The second value is an error message, in case the check failed.

AUTHOR

Gustavo L. de M. Chaves <gnustavo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by CPqD <www.cpqd.com.br>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Git::Hooks

perl -MCPAN -e shell
install Git::Hooks