Git Hooks Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev sweetchuck/git-hooks
   

2. Configure composer.json to point to your custom Git hooks directory:

   "extra": {
       "sweetchuck/git-hooks": {
           "core.hooksPath": "./git-hooks",
           "symlink": true
       }
   }
   

3. Create a git-hooks directory in your project root and add hook files (e.g., pre-commit, pre-push). Example git-hooks/pre-commit:

   #!/bin/sh
   echo "Running pre-commit checks..."
   # Add your logic here (e.g., PHPStan, Pest, etc.)
   

4. Trigger setup by running:

   composer install
   

   The package will symlink/copy hooks to .git/hooks/ automatically.

First Use Case: Enforcing Code Quality

Use pre-commit to block invalid commits:

#!/bin/sh
php artisan test:unit
php artisan pest

• Why? Ensures tests pass before commits land in the repo.
• Where? Place in git-hooks/pre-commit and commit the file to version control.

Implementation Patterns

Workflow: Centralized Hook Management

1. Store hooks in VCS: Commit git-hooks/ to share hooks across the team (e.g., pre-commit, pre-push).
2. Leverage Laravel Artisan: Call Artisan commands directly in hooks:

   # git-hooks/pre-commit
   php artisan migrate:status --no-interaction || exit 1
   

3. Modularize logic: Use Laravel’s app/Console/Kernel.php to define reusable hook tasks:

   protected function schedule(Schedule $schedule): void
   {
       $schedule->command('githook:pre-commit')->everyMinute();
   }
   

Integration Tips

• Combine with Laravel Forge/Envoyer: Deploy hooks alongside your app by committing git-hooks/ to the repo.
• Environment-specific hooks: Use core.hooksPath to override paths per environment (e.g., ./git-hooks/staging/).
• Debugging hooks: Add logging to hooks:

  #!/bin/sh
  echo "Hook triggered at $(date)" >> /tmp/git_hooks.log
  

Gotchas and Tips

Pitfalls

1. Symlink Permissions:

   • On Linux, ensure .git/hooks/ is writable:

     chmod -R u+w .git/hooks/
     

   • On macOS/Windows, disable symlink in config if permissions fail:

     "symlink": false
     

2. Git Version Mismatch:

   • If using Git < 2.9, core.hooksPath is ignored. Fall back to symlinks/copies.
   • Verify Git version:

     git --version
     

3. Hook Execution Order:

   • Hooks in git-hooks/ run after built-in Git hooks (e.g., pre-commit runs last).
   • Override order by modifying .git/hooks/ directly (not recommended for team sharing).

Debugging

1. Dry Run: Test hooks locally before committing:

   ./git-hooks/pre-commit
   

2. Check Symlinks: Verify hooks are linked:

   ls -la .git/hooks/ | grep pre-commit
   

3. Disable Hooks Temporarily: Rename .git/hooks/pre-commit to bypass it during debugging.

Extension Points

1. Custom Hook Logic: Extend ./.git-hooks.sh to support non-Robo scripts (e.g., Node.js):

   if command -v npm &> /dev/null; then
       npm run lint
   fi
   

2. Dynamic Hooks: Use Laravel’s config() to load hooks dynamically:

   #!/bin/sh
   HOOK_SCRIPT=$(php artisan config:get git-hooks.pre-commit)
   eval "$HOOK_SCRIPT"
   

3. CI/CD Integration: Skip hooks in CI by checking environment:

   if [ -z "$CI" ]; then
       # Run hook logic
   fi
   

Pro Tips

• Template Hooks: Store hook templates in resources/git-hooks/ and copy them to git-hooks/ during setup.
• Hook Validation: Add a post-checkout hook to validate hook files:

  #!/bin/sh
  [ -f "git-hooks/pre-commit" ] || echo "ERROR: Missing pre-commit hook!" >&2
  

• Performance: Cache hook outputs (e.g., PHPStan) to avoid redundant checks:

  # git-hooks/pre-commit
  if [ -f ".phpstan.cache" ]; then
      php artisan phpstan
  fi