butschster/laravel-git-hooks

Tools for managing git hooks for Laravel application

v0.7 2020-05-20 16:37 UTC

Requires

• php: >=7.2
• illuminate/config: ^5.6|^6.0|^7.0
• illuminate/console: ^5.6|^6.0|^7.0
• illuminate/container: ^5.6|^6.0|^7.0
• illuminate/contracts: ^5.6|^6.0|^7.0
• illuminate/pipeline: ^5.6|^6.0|^7.0
• illuminate/support: ^5.6|^6.0|^7.0

Requires (Dev)

• mockery/mockery: ^1.0
• phpunit/phpunit: ^7.0

MIT

• Pavel Buchnev

• git
• laravel5
• lumen
• laravel6
• git-hooks

README

Laravel Git Hooks manager is a beautiful tools for Laravel applications. It provides a simple and flexible API to manage git hooks, edit commit messages

Features

• Manage git hooks
• Edit commit messages
• Using custom hooks
• Well documented
• Well tested

Requirements

• Laravel 5.6 to 6.x
• PHP 7.2 and above

Installation

From the command line run

composer require --dev butschster/laravel-git-hooks

Register git hooks by running artisan command

php artisan git:register-hooks

That's it!

Configuration

Publish the config file.

php artisan vendor:publish --provider="Butschster\GitHooks\Providers\GitHooksServiceProvider" --tag=config

Hooks

Configuration

You can set list oh hooks for each of type git hook. You can do it in config/git_hooks.php. As a hook you can use class names, service containers and closure functions.

// App/Providers/AppServiceProvider

class AppServiceProvider extends ServiceProvider {
    pubflic function register() {
    
        $this->app->bind('my-first-hook', function ($app) {
            return new \App\Console\GitHooks\MyPreCommitHook();
        });

    }
}

// config/git_hooks.php
return [
    ...
    'pre-commit' => [
        // Just class name
        \App\Console\GitHooks\MyPreCommitHook::class,
        
        // Class name with params, which will be pass in constructor
        \App\Console\GitHooks\MyPreCommitHook::class => [
            'param1' => 'hello',
            'param2' => 'world'
        ], 
        
        // Closure function
        function(ChangedFiles $files, Closure $next) {
            return $next($files);
        },
        
        // Service container
        'my-first-hook'
    ],
    ...
];

Hook pre-commit

The pre-commit hook is run first, before you even type in a commit message. It’s used to inspect the snapshot that’s about to be committed, to see if you’ve forgotten something, to make sure tests run, or to examine whatever you need to inspect in the code. Exiting non-zero from this hook aborts the commit, although you can bypass it with git commit --no-verify. You can do things like check for code style (run lint or something equivalent), check for trailing whitespace (the default hook does exactly this), or check for appropriate documentation on new methods.

// config/git_hooks.php
return [
    ...
    'pre-commit' => [
        \App\Console\GitHooks\MyPreCommitHook::class,
    ],
    ...
];

// App/Console/GitHooks/MyPreCommitHook.php

namespace \App\Console\GitHooks;

use \Butschster\GitHooks\Git\ChangedFiles;
use Closure;

class MyPreCommitHook implements \Butschster\GitHooks\Contracts\PreCommitHook
{

    public function getName() : string
    {
        return '...';
    }

    public function handle(ChangedFiles $files, Closure $next)
    {
        // do something

        // If you want to cancel commit, you have to throw an exception.

        // run next hook
        return $next($files);
    }
}

Hook prepare-commit-msg

The prepare-commit-msg hook is run before the commit message editor is fired up but after the default message is created. It lets you edit the default message before the commit author sees it. This hook takes a few parameters: the path to the file that holds the commit message so far, the type of commit, and the commit SHA-1 if this is an amended commit. This hook generally isn’t useful for normal commits; rather, it’s good for commits where the default message is auto-generated, such as templated commit messages, merge commits, squashed commits, and amended commits. You may use it in conjunction with a commit template to programmatically insert information.

// config/git_hooks.php
return [
    ...
    'prepare-commit-msg' => [
        \App\Console\GitHooks\MyFirstPrepareCommitHook::class,
    ],
    ...
];

// App/Console/GitHooks/MyFirstPrepareCommitHook.php

namespace \App\Console\GitHooks;

use Butschster\GitHooks\Git\CommitMessage;
use Closure;

class MyFirstPrepareCommitHook implements \Butschster\GitHooks\Contracts\MessageHook
{
    public function getName() : string
    {
        return '...';
    }

    public function handle(CommitMessage $message, Closure $next)
    {
        // do something

        $currentMessage = $message->getMessage();

        // You can update commit message text
        $message->setMessage(str_replace('issue', 'fixed', $currentMessage));

        // If you want to cancel commit, you have to throw an exception.

        // run next hook
        return $next($message);
    }
}

Hook commit-msg

The commit-msg hook takes one parameter, which again is the path to a temporary file that contains the commit message written by the developer. If this script exits non-zero, Git aborts the commit process, so you can use it to validate your project state or commit message before allowing a commit to go through.

// config/git_hooks.php
return [
    ...
    'commit-msg' => [
        \App\Console\GitHooks\MyFirstCommitMessageHook::class,
    ],
    ...
];

// App/Console/GitHooks/MyFirstCommitMessageHook.php

namespace \App\Console\GitHooks;

use Butschster\GitHooks\Git\CommitMessage;
use Closure;

class MyFirstCommitMessageHook implements \Butschster\GitHooks\Contracts\MessageHook
{
    public function getName() : string
    {
        return '...';
    }

    public function handle(CommitMessage $message, Closure $next)
    {
        // do something

        $currentMessage = $message->getMessage();

        // You can update commit message text
        $message->setMessage(str_replace('issue', 'fixed', $currentMessage));

        // If you want to cancel commit, you have to throw an exception.

        // run next hook
        return $next($message);
    }
}

Hook post-commit

After the entire commit process is completed, the post-commit hook runs. It doesn’t take any parameters, but you can easily get the last commit by running git log -1 HEAD. Generally, this script is used for notification or something similar.

// config/git_hooks.php
return [
    ...
    'post-commit' => [
        \App\Console\GitHooks\NotifyAboutNewCommit::class,
    ],
    ...
];

// App/Console/GitHooks/NotifyAboutNewCommit.php

namespace \App\Console\GitHooks;

use Butschster\GitHooks\Git\Log;
use Closure;

class NotifyAboutNewCommit implements \Butschster\GitHooks\Contracts\PostCommitHook
{
    public function getName() : string
    {
        return '...';
    }

    public function handle(Log $log, Closure $next)
    {
        $hash = $log->getHash();
        $author = $log->getAuthor();
        $date = $log->getDate();
        $message = $log->getMessage();

        // do something

        // If you want to cancel, you have to throw an exception.

        // run next hook
        return $next($log);
    }
}