CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/go-lefthook

A Git hooks manager for Node.js, Ruby, Python and many other types of projects, written in Go for speed and cross-platform compatibility.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Lefthook

Lefthook is a fast Git hooks manager written in Go that allows you to control execution and files for your Git hooks across multiple programming languages and environments. It provides a single dependency-free binary that can execute hooks in parallel, filter files using glob patterns, support Docker environments, and manage complex hook configurations through YAML files.

Package Information

  • Package Name: lefthook
  • Package Type: CLI tool / Git hooks manager
  • Language: Go
  • Installation:
    • Go: go install github.com/evilmartians/lefthook@latest
    • NPM: npm install lefthook --save-dev
    • Ruby: gem install lefthook
    • Python: pip install lefthook

Core Usage

Binary Execution

lefthook --help

Go Library Integration

import "github.com/evilmartians/lefthook/cmd"

func main() {
    exitCode := cmd.Lefthook()
    os.Exit(exitCode)
}

Basic Usage

# Install hooks in repository
lefthook install

# Run specific hook
lefthook run pre-commit

# Add new hook configuration
lefthook add pre-commit

# Validate configuration
lefthook validate

# Check installation status
lefthook check_install

# Remove hooks
lefthook uninstall

# Export configuration
lefthook dump

# Update lefthook binary
lefthook self-update

# Display version information
lefthook version

Architecture

Lefthook uses a YAML-based configuration system (.lefthook.yml or lefthook.yml) to define Git hooks and their execution parameters. The system supports:

  • Parallel Execution: Run multiple commands concurrently
  • File Filtering: Use glob patterns and regex to target specific files
  • Conditional Execution: Skip commands based on Git state or custom conditions
  • Template Variables: Dynamic file and context substitution
  • Script Integration: Execute custom scripts alongside commands
  • Docker Support: Run commands in containerized environments
  • Tag-based Organization: Group and filter commands by tags

Capabilities

CLI Commands

Primary command interface for managing Git hooks.

lefthook [command] [flags]

# Global flags:
--verbose, -v     # Enable verbose output
--colors string   # Color output: 'auto', 'on', or 'off' (default "auto")
--no-colors       # Disable colored output (deprecated)

CLI Commands

Configuration System

YAML-based hook configuration with comprehensive options.

# Global configuration options
assert_lefthook_installed: boolean  # Require lefthook installation
skip_lfs: boolean                   # Skip LFS files
colors: boolean                     # Enable colored output
no_tty: boolean                     # Disable TTY output
extend: string                      # Extend from remote configuration

# Hook definitions
pre-commit:
  parallel: boolean                 # Run commands in parallel
  piped: boolean                   # Pipe commands together
  follow: boolean                  # Follow up execution on failure
  exclude_tags: [string]           # Tags to exclude
  skip: [merge|rebase]             # Skip conditions
  only: [merge|rebase]             # Only run conditions
  commands: { [string]: Command }  # Command definitions
  scripts: { [string]: Script }   # Script definitions

Configuration System

Hook Execution Engine

Core engine for running Git hooks with file filtering and parallel execution.

// Main entry point
func cmd.Lefthook() int

// Command execution options
type command.Options struct {
    Verbose  bool   // Enable verbose logging
    Colors   string // Color output setting
    NoColors bool   // Disable colors (deprecated)
}

// Run arguments for hook execution
type command.RunArgs struct {
    NoTTY           bool     // Disable TTY output
    AllFiles        bool     // Process all files instead of staged
    FilesFromStdin  bool     // Get files from stdin
    Force           bool     // Force execution of skippable commands
    NoAutoInstall   bool     // Skip updating git hooks
    SkipLFS         bool     // Skip running git lfs
    Verbose         bool     // Enable verbose output
    Exclude         []string // Files to exclude
    Files           []string // Specific files to process
    RunOnlyCommands []string // Run only specified commands
    RunOnlyJobs     []string // Run only specified jobs
}

Hook Execution

Types

Command Configuration

Command:
  run: string                    # Command to execute
  glob: string                   # File matching pattern
  files: string                  # Git command for file list
  root: string                   # Execution directory
  exclude: string                # Files to exclude (regex)
  tags: [string]                 # Command tags
  env: { [string]: string }      # Environment variables
  fail_text: string              # Custom failure message
  skip: [merge|rebase] | boolean # Skip conditions
  only: [merge|rebase] | boolean # Only run conditions
  stage_fixed: boolean           # Stage fixed files
  interactive: boolean           # Interactive execution
  use_stdin: boolean             # Use standard input
  priority: integer              # Execution priority

Script Configuration

Script:
  runner: string                 # Script runner (bash, node, python, etc.)
  env: { [string]: string }      # Environment variables
  fail_text: string              # Custom failure message
  skip: [merge|rebase] | boolean # Skip conditions
  only: [merge|rebase] | boolean # Only run conditions
  stage_fixed: boolean           # Stage fixed files
  interactive: boolean           # Interactive execution
  use_stdin: boolean             # Use standard input
  priority: integer              # Execution priority

Template Variables

# Available template variables for commands and scripts
{files}          # Files matched by glob pattern after filtering
{staged_files}   # Git staged files (unfiltered)
{push_files}     # Files being pushed (for pre-push hook)
{all_files}      # All repository files
{0}              # All command-line arguments passed to git hook
{1}              # First positional argument
{2}              # Second positional argument
{lefthook_job_name}  # Name of the current job being executed

Error Handling

Lefthook provides comprehensive error handling and reporting:

  • Exit Codes: Returns 0 for success, 1 for errors
  • Verbose Logging: Detailed execution information with -v flag
  • Custom Failure Messages: fail_text option for commands and scripts
  • Graceful Degradation: Continues execution when possible
  • Configuration Validation: Validates YAML configuration before execution

docs

cli-commands.md

configuration.md

hook-execution.md

index.md

tile.json