Gustavo Leite de Mendonça Chaves > Git-Hooks-0.033 > Git::More

Download:
Git-Hooks-0.033.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.033   Source   Latest Release: Git-Hooks-0.047

NAME ^

Git::More - A Git extension with some goodies for hook developers.

VERSION ^

version 0.033

SYNOPSIS ^

    use Git::More;

    my $git = Git::More->repository();

    my $config  = $git->get_config();
    my $branch  = $git->get_current_branch();
    my $commits = $git->get_commits($oldcommit, $newcommit);
    my $message = $git->get_commit_msg('HEAD');

    my $files_modified_by_commit = $git->get_diff_files('--diff-filter=AM', '--cached');
    my $files_modified_by_push   = $git->get_diff_files('--diff-filter=AM', $oldcommit, $newcommit);

DESCRIPTION ^

This is an extension of the Git class. It's meant to implement a few extra methods commonly needed by Git hook developers.

In particular, it's used by the standard hooks implemented by the Git::Hooks framework.

METHODS ^

get_config [SECTION [VARIABLE]]

This method groks the configuration options for the repository by invoking git config --list. The configuration is cached during the first invokation in the object Git::More object. So, if the configuration is changed afterwards, the method won't notice it. This is usually ok for hooks, though.

With no arguments, the options are returned as a hash-ref pointing to a two-level hash. For example, if the config options are these:

    section1.a=1
    section1.b=2
    section1.b=3
    section2.x.a=A
    section2.x.b=B
    section2.x.b=C

Then, it'll return this hash:

    {
        'section1' => {
            'a' => [1],
            'b' => [2, 3],
        },
        'section2.x' => {
            'a' => ['A'],
            'b' => ['B', 'C'],
        },
    }

The first level keys are the part of the option names before the last dot. The second level keys are everything after the last dot in the option names. You won't get more levels than two. In the example above, you can see that the option "section2.x.a" is split in two: "section2.x" in the first level and "a" in the second.

The values are always array-refs, even it there is only one value to a specific option. For some options, it makes sense to have a list of values attached to them. But even if you expect a single value to an option you may have it defined in the global scope and redefined in the local scope. In this case, it will appear as a two-element array, the last one being the local value.

So, if you want to treat an option as single-valued, you should fetch it like this:

    $h->{section1}{a}[-1]
    $h->{'section2.x'}{a}[-1]

If the SECTION argument is passed, the method returns the second-level hash for it. So, following the example above, this call:

    $git->get_config('section1');

This call would return this hash:

    {
        'a' => [1],
        'b' => [2, 3],
    }

If the section don't exist an empty hash is returned. Any key/value added to the returned hash will be available in subsequent invokations of get_config.

If the VARIABLE argument is also passed, the method returns the value(s) of the configuration option SECTION.VARIABLE. In list context the method returns the list of all values or the empty list, if the variable isn't defined. In scalar context, the method returns the variable's last value or undef, if it's not defined.

cache SECTION

This method may be used by plugin developers to cache information in the context of a Git::More object. SECTION is a string (usually a plugin name) that is associated with a hash-ref. The method simply returns the hash-ref, which can be used by the caller to store any kind of information.

get_commits OLDCOMMIT NEWCOMMIT

This method returns a list of hashes representing every commit reachable from NEWCOMMIT but not from OLDCOMMIT. It obtains this information by invoking git rev-list OLDCOMIT..NEWCOMMIT.

Each commit is represented by a hash with the following structure (the codes are explained in the git help rev-list document):

    {
        commit          => %H:  commit hash
        tree            => %T:  tree hash
        parent          => %P:  parent hashes (space separated)
        author_name     => %aN: author name
        author_email    => %aE: author email
        author_date     => %ai: author date in ISO8601 format
        commmitter_name => %cN: committer name
        committer_email => %cE: committer email
        committer_date  => %ci: committer date in ISO8601 format
        body            => %B:  raw body (aka commit message)
    }

get_commit_msg COMMIT_ID

This method returns the commit message (a.k.a. body) of the commit identified by COMMIT_ID. The result is a string.

get_diff_files DIFFARGS...

This method invokes the command git diff --name-status with extra options and arguments as passed to it. It returns a reference to a hash mapping every affected files to their affecting status. Its purpose is to make it easy to grok the names of files affected by a commit or a sequence of commits. Please, read git help diff to know everything about its options.

A common usage is to grok every file added or modified in a pre-commit hook:

    my $hash_ref = $git->get_diff_files('--diff-filter=AM', '--cached');

Another one is to grok every file added or modified in a pre-receive hook:

    my $hash_ref = $git->get_diff_files('--diff-filter=AM', $old_commit, $new_commit);

set_affected_ref REF OLDCOMMIT NEWCOMMIT

This method should be used in the beginning of an update, pre-receive, or post-receive hook in order to record the references that were affected by the push command. The information recorded will be later used by the following get_affected_ref* methods.

get_affected_refs

This method returns the list of names of references that were affected by the current push command, as they were set by calls to the set_affected_ref method.

get_affected_ref_range(REF)

This method returns the two-element list of commit ids representing the OLDCOMMIT and the NEWCOMMIT of the affected REF.

get_affected_ref_commit_ids(REF)

This method returns the list of commit ids leading from the affected REF's NEWCOMMIT to OLDCOMMIT.

get_affected_ref_commits(REF)

This routine returns the list of commits leading from the affected REF's NEWCOMMIT to OLDCOMMIT. The commits are represented by hashes, as returned by the get_commits method.

authenticated_user

This method returns the username of the authenticated user performing the Git action. It groks it from the githooks.userenv configuration variable specification, which is described in the Git::Hooks documentation. It's useful for most access control check plugins.

get_current_branch

This method returns the repository's current branch name, as indicated by the git branch command. Note that it's a ref short name, i.e., it's usually sub-intended to reside under the 'refs/heads/' ref scope.

SEE ALSO ^

Git

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: