Lefthook

Common errors

• Can't find lefthook in PATH

  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.
  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.

• Git commit hangs indefinitely / commands pop up in new window (Windows)

  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.
  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.

• Git commit hangs indefinitely when internet connection is unavailable

  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.
  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.

• Lefthook git output with ESC characters is unreadable in VSCode

  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.
  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.

• error getting file: exit 128 (often with pre-push hook)

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install lefthook Install with pip
• pipx install lefthook Install with pipx (recommended for CLI tools)

Quickstart

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.

#!/bin/bash
# .github/workflows/verify-hooks.yml (example for CI)

# Install lefthook (e.g., in CI or dev setup)
pip install lefthook

# Initialize lefthook configuration
lefthook install

# Example lefthook.yml content (create this file in your project root)
# pre-commit:
#   parallel: true
#   commands:
#     lint:
#       glob: "*.py"
#       run: flake8 {staged_files}
#     format:
#       glob: "*.py"
#       run: black {staged_files}
#       stage_fixed: true

# To run hooks manually (e.g., for testing):
# lefthook run pre-commit