Gustavo Leite de Mendonça Chaves > Git-Hooks-0.046 > Git::Hooks::CheckStructure

Download:
Git-Hooks-0.046.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.046   Source   Latest Release: Git-Hooks-0.049

NAME ^

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

VERSION ^

version 0.046

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.

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.

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

syntax highlighting: