githooks

Overview ¶

Package githooks provides Git hook installation and management for Hitch repositories.

Overview ¶

This package handles the installation of Git hooks that integrate with Hitch to provide automatic validation and safety checks. It creates shell scripts in the .git/hooks directory that invoke Hitch commands.

Installed Hooks ¶

The package currently installs one primary hook:

• pre-commit: Validates hitch.json when it's modified in a commit

Pre-Commit Hook ¶

The pre-commit hook ensures hitch.json is always valid:

#!/bin/sh
# Hitch pre-commit hook - validates hitch.json on changes
set -e

# Check if hitch.json is in the commit
if git diff --cached --name-only | grep -q "hitch.json"; then
    echo "Validating hitch.json..."
    if ! hitch validate; then
        echo "Error: hitch.json validation failed"
        exit 1
    fi
    echo "✓ hitch.json is valid"
fi

This prevents committing invalid hitch.json files that would break Hitch operations.

Installation ¶

Install hooks via the command line:

hitch install-hooks

Or programmatically:

import (
    "github.com/DoomedRamen/hitch/internal/git"
    "github.com/DoomedRamen/hitch/internal/githooks"
)

repo, err := git.OpenRepo(".")
if err != nil {
    return err
}

err = githooks.InstallPreCommitHook(repo)
if err != nil {
    return fmt.Errorf("failed to install hooks: %w", err)
}

Hook Behavior ¶

When hitch.json is modified:

1. Pre-commit hook detects the change
2. Runs 'hitch validate' command
3. If validation passes: commit proceeds
4. If validation fails: commit is blocked with error message

Hook Location ¶

Hooks are installed to:

.git/hooks/pre-commit

The installer:

• Creates the hooks directory if it doesn't exist
• Sets executable permissions (0755)
• Preserves existing hooks by appending Hitch logic

Safety Features ¶

The hook installation implements safety mechanisms:

• Checks if hitch command is available in PATH
• Only runs on hitch.json changes (doesn't slow down other commits)
• Provides clear error messages when validation fails
• Exits with appropriate status codes

User Experience ¶

Example commit flow with hooks installed:

$ git add hitch.json
$ git commit -m "Update environment config"
Validating hitch.json...
✓ hitch.json is valid
[main abc123] Update environment config
 1 file changed, 5 insertions(+), 2 deletions(-)

Example when validation fails:

$ git add hitch.json
$ git commit -m "Update config"
Validating hitch.json...
❌ Error: environment 'devv' not found in configuration

Error: hitch.json validation failed

Integration with Lefthook ¶

While this package provides native Git hooks, users can also integrate with lefthook or other hook managers by using hitch hook commands:

# In lefthook.yml
pre-commit:
  commands:
    hitch-validate:
      glob: "hitch.json"
      run: hitch validate

Future Hooks ¶

Additional hooks may be added in the future:

• pre-push: Prevent pushing to hitched environment branches
• post-checkout: Warn when checking out hitched branches
• commit-msg: Validate commit message format

Testing ¶

The package includes integration tests:

• githooks_test.go: Hook installation and execution tests

Tests verify:

• Hook files are created with correct permissions
• Hooks execute and validate hitch.json correctly
• Hooks properly block invalid commits
• Hooks don't interfere with non-hitch commits

Dependencies ¶

External dependencies:

• os/exec: For executing git commands

Internal dependencies:

• internal/git: Repository operations

Example: Hook Installation Workflow ¶

// During hitch init
repo, err := git.OpenRepo(".")
if err != nil {
    return err
}

// Initialize Hitch configuration
// ... initialize metadata, create hitch.json, etc.

// Install hooks
fmt.Println("Installing Git hooks...")
err = githooks.InstallPreCommitHook(repo)
if err != nil {
    fmt.Printf("Warning: Could not install hooks: %v\n", err)
    fmt.Println("You can install them later with: hitch install-hooks")
} else {
    fmt.Println("✓ Git hooks installed successfully")
}

Error Handling ¶

Hook installation errors are non-fatal:

• Missing .git directory: Returns error with explanation
• Permission denied: Returns error suggesting chmod/sudo
• Missing hitch binary: Hook warns user at execution time

Best Practices ¶

For teams using Hitch:

1. Install hooks during onboarding: Include 'hitch install-hooks' in setup docs
2. Commit hook configs: If using lefthook, commit lefthook.yml
3. Document hook behavior: Explain validation to team members
4. Test hooks work: Run 'hitch validate' manually to verify setup