{"id":8270,"library":"lefthook","title":"Lefthook","description":"Lefthook is a fast, powerful, and simple Git hooks manager. Written in Go, it streamlines development workflows by automating tasks like linting and testing during Git operations. It is actively maintained with frequent releases, currently at version 2.1.6, often seeing updates on a monthly or bi-monthly cadence.","status":"active","version":"2.1.6","language":"en","source_language":"en","source_url":"https://github.com/evilmartians/lefthook","tags":["git","hooks","automation","dev-tools","cli"],"install":[{"cmd":"pip install lefthook","lang":"bash","label":"Install with pip"},{"cmd":"pipx install lefthook","lang":"bash","label":"Install with pipx (recommended for CLI tools)"}],"dependencies":[],"imports":[],"quickstart":{"code":"#!/bin/bash\n# .github/workflows/verify-hooks.yml (example for CI)\n\n# Install lefthook (e.g., in CI or dev setup)\npip install lefthook\n\n# Initialize lefthook configuration\nlefthook install\n\n# Example lefthook.yml content (create this file in your project root)\n# pre-commit:\n#   parallel: true\n#   commands:\n#     lint:\n#       glob: \"*.py\"\n#       run: flake8 {staged_files}\n#     format:\n#       glob: \"*.py\"\n#       run: black {staged_files}\n#       stage_fixed: true\n\n# To run hooks manually (e.g., for testing):\n# lefthook run pre-commit","lang":"bash","description":"After installing, create a `lefthook.yml` file in your project root to define hooks. Then, run `lefthook install` to set up the Git hooks. The provided `lefthook.yml` snippet demonstrates a `pre-commit` hook that runs `flake8` for linting and `black` for formatting on staged Python files, automatically staging `black`'s fixes. Lefthook runs commands in parallel by default, improving efficiency."},"warnings":[{"fix":"Review your `lefthook.yml` configuration and CLI usage against the v2 documentation. Update `exclude` patterns to use globs, replace `skip_output` with `output`, and adjust CLI commands as needed.","message":"Version 2.0.0 introduced significant breaking changes. The `exclude` option no longer accepts regular expressions, only globs. The `skip_output` option was removed, replaced by `output`. Several CLI arguments were renamed for consistency.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure the `lefthook` executable's directory is correctly added to your system's PATH. For hanging or new window issues, try disabling `parallel: true` for problematic hooks on Windows, or explore specific `runner` configurations if applicable. Recent versions have improved Windows path normalization.","message":"On Windows, `lefthook` commands might fail with 'Can't find lefthook in PATH', or hooks configured with `parallel: true` can hang or cause new command windows to briefly pop up. This is often related to PATH configuration or process handling specifics on Windows.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Ensure `lefthook` is installed globally (e.g., via `pipx install lefthook`) rather than relying on `npx`. If remote configs are used, ensure they are cached or accessible offline, or use `LEFTHOOK=0 git commit` to bypass hooks when offline.","message":"Running `git commit` or other hooks can hang indefinitely if your system loses internet connectivity, especially if `lefthook` is configured to fetch remote configurations or if `npx` is used as a fallback for command execution.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure the tools used in your `lefthook` commands (e.g., linters, formatters) to output without colors. For instance, many tools support a `--no-color` or `--color=never` flag.","message":"In certain VSCode/WSL2 setups, `lefthook` output in the Git output panel may appear unreadable due to uninterpreted ANSI color escape codes. This happens when tools output colors, but the rendering environment doesn't support them.","severity":"gotcha","affected_versions":"All versions with affected terminal/IDE setups"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Manually add the directory containing the `lefthook` executable to your system's PATH. If installed via npm, this might be `%APPDATA%\\npm` or similar; for pipx, it's typically `~/.local/bin` on Linux/macOS or `%USERPROFILE%\\AppData\\Roaming\\Python\\Scripts` on Windows.","cause":"The `lefthook` executable is not located in any directory listed in the system's PATH environment variable, particularly common on Windows systems after global npm installs.","error":"Can't find lefthook in PATH"},{"fix":"Disable `parallel: true` for the affected hooks in `lefthook.yml` when on Windows. Ensure `lefthook` is updated to the latest version for relevant fixes. Investigate specific commands that trigger the issue and adjust their execution or use `no_tty: true` in `lefthook.yml` as a potential workaround if applicable.","cause":"Lefthook's process management, especially with `parallel: true` or `sh -c` wrappers, can lead to child processes hanging or spawning new windows on Windows due to shell interaction differences.","error":"Git commit hangs indefinitely / commands pop up in new window (Windows)"},{"fix":"Ensure `lefthook` is installed locally via pip/pipx rather than relying on `npx` in hooks. If you have remote configs, manage them carefully. As a temporary workaround, prepend `LEFTHOOK=0` to your `git commit` command (e.g., `LEFTHOOK=0 git commit -m \"fix\"`) to bypass hooks.","cause":"Lefthook might attempt to access network resources (e.g., update its binary, fetch remote configurations, or use `npx` for fallback command execution) and get stuck if the internet is not available.","error":"Git commit hangs indefinitely when internet connection is unavailable"},{"fix":"Modify the commands in your `lefthook.yml` to explicitly disable colored output. For example, use `eslint --no-color`, `prettier --color always`, or similar options for your linters/formatters.","cause":"When `lefthook` runs commands that output ANSI color codes, and the VSCode Git output panel or integrated terminal in WSL2 doesn't interpret these codes, they appear as raw escape sequences.","error":"Lefthook git output with ESC characters is unreadable in VSCode"},{"fix":"Ensure your local branch is tracking an upstream branch (e.g., `git push -u origin your-branch`). Double-check the `glob` patterns in your `lefthook.yml` to ensure they correctly identify files for the intended commands.","cause":"This error can occur if `lefthook` is unable to resolve Git HEAD, often when a local branch is not tracking a remote branch, or if there's a misconfigured `glob` pattern in `lefthook.yml` that doesn't match any files.","error":"error getting file: exit 128 (often with pre-push hook)"}]}