NAME

Git::Hook::PostReceive - Parses git commit information in post-receive hook scripts

VERSION

version 0.3

SYNOPSIS

    # hooks/post-receive
    use Git::Hook::PostReceive;

    my @branches = Git::Hook::PostReceive->new->read_stdin;
    foreach my $payload (@branches) {

        $payload->{before};
        $payload->{after};

        for my $commit (@{ $payload->{commits} } ) {
            $commit->{id};
            $commit->{author}->{name};
            $commit->{author}->{email};
            $commit->{message};
            $commit->{date};
        }
    }

    # hooks/post-receive to send web hooks like GitHub
    use Git::Hook::PostReceive 0.2;
    use LWP::UserAgent;
    use JSON;

    my $ua = LWP::UserAgent->new;
    for (Git::Hook::PostReceive->new( utf8 => 1 )->read_stdin) {
        $ua->post( "http://example.org/webhook", { 'payload' => to_json($_) } );
    }

DESCRIPTION

Git::Hook::PostReceive parses git commit information in post-receive hook script.

All you need to do is pass each STDIN string to Git::Hook::PostReceive, then it returns the commit payload for the particular branch.

This module does not use any non-core dependencies, so you can also copy it to a location of your choice and directly include it.

To run the hook on an arbitrary git repository, set the GIT_WORK_TREE environment variable.

payload format

The payload format returned by method read_stdin or run is compatible with https://help.github.com/articles/post-receive-hooks with some minor differences:

    {
        before  => $commit_hash_before,
        after   => $commit_hash_after,
        ref     => $ref,
        created => $whether_new_branch,      # 1|0 in contrast to true|false
        deleted => $whether_branch_removed,  # 1|0 in contrast to true|false
        commits => [
            id        => $hash,
            message   => $message,
            timestamp => $date,
            author    => {
                email => $email,
                name  => $name
            },
            commiter  => {
                email => $email,
                name  => $name
            },
            added     => [@added_paths],
            removed   => [@deleted_paths],
            modified  => [@modified_paths],
        ],
        repository => $directory,           # in contrast to detailed object
    }

before is set to <0000000000000000000000000000000000000000> and created is set to 1 (0 otherwise) when a new branch has been pushed. after is set to <0000000000000000000000000000000000000000> and deleted is set to 1 (0 otherwise) when a branch has been deleted.

CONFIGURATION

utf8

Git does not know about character encodings, so the payload will consists of raw byte strings by default. Setting this configuration value to a true value will decode all payload fields as UTF8 to get Unicode strings.

METHODS

read_stdin( [ @lines ] )

Read one or more lines as passed to a git post-receive hook. One can pass arrays of lines or strings that are split by newlines. Lines are read from STDIN by default.

run( $before, $after, $ref )

Return a payload for the commits between $before and $after at branch $ref. Returns undef on failure.

detect_action($before, $after)

This function detects the action of the receiving commits and return the action name with the related commit hash in a hashref.

0000000000 at the head means "branch created".

0000000000 at the end means "branch deleted".

Otherwise it means "commits pushed".

SEE ALSO

Git::Repository, Plack::App::GitHub::WebHook

CONTRIBUTORS

• Jakob Voss <voss@gbv.de>

• Yo-An Lin <cornelius@cpan.org>

AUTHOR

Yo-An Lin

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Yo-An Lin.

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::Hook::PostReceive

perl -MCPAN -e shell
install Git::Hook::PostReceive