{"id":79428,"date":"2026-10-20T04:51:26","date_gmt":"2026-10-20T04:51:26","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=79428"},"modified":"2026-10-20T04:51:30","modified_gmt":"2026-10-20T04:51:30","slug":"how-to-install-and-configure-pre-commit-on-macos-windows-and-linux-complete-step-by-step-guide","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/how-to-install-and-configure-pre-commit-on-macos-windows-and-linux-complete-step-by-step-guide\/","title":{"rendered":"How to Install and Configure pre-commit on macOS, Windows, and Linux: Complete Step-by-Step Guide"},"content":{"rendered":"\n

SEO Title:<\/strong> How to Install and Configure pre-commit on Mac, Windows & Linux (2026)<\/p>\n\n\n\n

Meta Description:<\/strong> Learn how to install and configure pre-commit Git hooks on macOS, Windows, Ubuntu, Debian, and RHEL. Includes installation commands, YAML configuration, automatic linting, formatting, CI\/CD integration, and troubleshooting.<\/p>\n\n\n\n

Focus Keywords:<\/strong> pre-commit installation, install pre-commit macOS, pre-commit Windows, pre-commit Ubuntu, pre-commit Linux, pre-commit Git hooks, pre-commit config YAML, pre-commit Terraform, pre-commit Python, pre-commit GitHub Actions<\/p>\n\n\n\n

\n\n\n\n

1. Introduction<\/h2>\n\n\n\n

Writing clean, secure, and maintainable code is an essential part of modern software development.<\/p>\n\n\n\n

However, even experienced developers occasionally introduce issues such as trailing whitespace, incorrectly formatted code, invalid YAML files, debugging statements, oversized files, or accidentally committed credentials.<\/p>\n\n\n\n

Finding these issues during code review or after merging changes can waste valuable development time.<\/p>\n\n\n\n

This is where pre-commit<\/strong> becomes useful.<\/p>\n\n\n\n

pre-commit is an open-source framework for managing Git hooks that automatically checks your code before a commit is created.<\/p>\n\n\n\n

It can run formatting tools, linters, configuration validators, and security-related checks without requiring developers to manually execute each tool.<\/p>\n\n\n\n

For example, when a developer executes:<\/p>\n\n\n

git commit -m \"Add new feature\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
pre-commit can automatically:<\/p>\n\n\n\n
    \n
  • Remove trailing whitespace.<\/li>\n\n\n\n
  • Fix missing end-of-file newlines.<\/li>\n\n\n\n
  • Validate YAML, JSON, and TOML files.<\/li>\n\n\n\n
  • Check for unresolved Git merge conflicts.<\/li>\n\n\n\n
  • Identify certain accidentally included private keys.<\/li>\n\n\n\n
  • Prevent unexpectedly large files from being committed.<\/li>\n\n\n\n
  • Format Python or Terraform files when suitable hooks are configured.<\/li>\n\n\n\n
  • Run additional code-quality checks.<\/li>\n<\/ul>\n\n\n\n
    In this tutorial, we will install and configure pre-commit across macOS, Windows, and Linux, build a practical Git hook configuration, and integrate it into everyday development workflows.<\/p>\n\n\n\n
    2. What Is pre-commit?<\/h2>\n\n\n\n
    pre-commit is a framework that manages and executes Git hooks.<\/p>\n\n\n\n
    Git hooks are scripts that run automatically when specific Git operations occur.<\/p>\n\n\n\n
    The most common example is the pre-commit<\/code> hook, which runs before Git finalizes a commit.<\/p>\n\n\n\n
    Instead of maintaining custom scripts individually, pre-commit lets developers describe their required checks in a single configuration file:<\/p>\n\n\n
    .pre-commit-config<\/span>.yaml<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    The framework downloads supported hooks, creates isolated environments, and executes those hooks against applicable files.<\/p>\n\n\n\n
    How pre-commit Works<\/h3>\n\n\n
    Developer changes files\n         |\n         v\n    git add files\n         |\n         v\n      git commit\n         |\n         v\n  Git pre-commit hook\n         |\n         v\n  pre-commit framework\n         |\n         v\n  Execute configured checks\n         |\n     +---+---+\n     |       |\n    PASS    FAIL\n     |       |\n     v       v\n Commit    Commit blocked\n created   Fix errors\n                |\n                v\n           Stage changes\n                |\n                v\n           Retry commit<\/code><\/span><\/pre>\n\n\n
    Some hooks only report issues, while others automatically modify files to fix problems.<\/p>\n\n\n\n
    If a hook modifies a file, you generally need to stage the changes again before committing.<\/p>\n\n\n\n
    Why Use pre-commit?<\/h3>\n\n\n\n
    Without pre-commit<\/th>With pre-commit<\/th><\/tr>
    Developers manually run formatting commands<\/td>Formatting runs automatically<\/td><\/tr>
    Invalid configuration may reach code review<\/td>Syntax errors can be detected before committing<\/td><\/tr>
    Inconsistent coding styles<\/td>Consistent checks across contributors<\/td><\/tr>
    More avoidable code-review comments<\/td>Many simple issues are corrected locally<\/td><\/tr>
    Each developer maintains separate scripts<\/td>Shared configuration in Git<\/td><\/tr>
    Accidental mistakes reach CI\/CD<\/td>Many errors are caught earlier<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Important:<\/strong> pre-commit is not a replacement for automated tests, code reviews, security scanning, or CI\/CD pipelines. It provides an additional layer of checks earlier in the development lifecycle.<\/p>\n\n\n\n
    \n\n\n\n
    3. Prerequisites<\/h2>\n\n\n\n
    Before installing pre-commit, ensure your system has the following components.<\/p>\n\n\n\n
    Requirement<\/th>Description<\/th><\/tr>
    Operating system<\/td>macOS, Windows, or Linux<\/td><\/tr>
    Git<\/td>Required for Git hook integration<\/td><\/tr>
    Python<\/td>Python 3.11 or newer for pre-commit 4.7.0<\/td><\/tr>
    Internet<\/td>Required to download packages and hook dependencies<\/td><\/tr>
    Terminal<\/td>Bash, Zsh, PowerShell, or compatible terminal<\/td><\/tr>
    Git repository<\/td>Required for installing project-specific hooks<\/td><\/tr>
    Package manager<\/td>Homebrew, pipx, pip, or another supported method<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    pre-commit itself requires Python, but it can manage hooks written in many programming languages.<\/p>\n\n\n\n
    Check Git Installation<\/h3>\n\n\n\n
    On macOS or Linux:<\/p>\n\n\n
    git --version<\/code><\/span><\/pre>\n\n\n
    On Windows PowerShell:<\/p>\n\n\n
    git --version<\/code><\/span><\/pre>\n\n\n
    Example output:<\/p>\n\n\n
    git<\/span> version<\/span> 2.x<\/span>.x<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    If Git is missing, install it from:<\/p>\n\n\n\n
    \nhttps:\/\/git-scm.com\/downloads\n<\/div><\/figure>\n\n\n\n
    Check Python Installation<\/h3>\n\n\n\n
    On macOS or Linux:<\/p>\n\n\n
    python3 --version<\/code><\/span><\/pre>\n\n\n
    On Windows:<\/p>\n\n\n
    py --version<\/code><\/span><\/pre>\n\n\n
    Expected version:<\/p>\n\n\n
    Python<\/span> 3.11<\/span>.x<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Or newer.<\/p>\n\n\n\n
    Check Whether pre-commit Is Already Installed<\/h3>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n\n
    If installed, the command returns a version such as:<\/p>\n\n\n
    pre-commit<\/span> 4.7<\/span>.0<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Otherwise, follow the installation instructions below.<\/p>\n\n\n\n
    \n\n\n\n
    4. How to Install pre-commit on macOS<\/h1>\n\n\n\n
    macOS users can install pre-commit using Homebrew, pipx, or Python pip.<\/p>\n\n\n\n
    For most Mac users, Homebrew is the recommended option.<\/p>\n\n\n\n
    Method 1: Install pre-commit Using Homebrew (Recommended)<\/h2>\n\n\n\n
    Step 1: Open Terminal<\/h3>\n\n\n\n
    Open Terminal from:<\/p>\n\n\n\n
    Applications \u2192 Utilities \u2192 Terminal<\/p>\n\n\n\n
    Step 2: Check macOS Version<\/h3>\n\n\n
    sw_vers<\/code><\/span><\/pre>\n\n\n
    Check processor architecture:<\/p>\n\n\n
    uname -m<\/code><\/span><\/pre>\n\n\n
    Apple Silicon:<\/p>\n\n\n
    arm64<\/code><\/span><\/pre>\n\n\n
    Intel Mac:<\/p>\n\n\n
    x86_64<\/code><\/span><\/pre>\n\n\n
    Homebrew supports compatible pre-commit installations on both architectures.<\/p>\n\n\n\n
    Step 3: Check Homebrew<\/h3>\n\n\n
    brew --version<\/code><\/span><\/pre>\n\n\n
    If Homebrew is not installed, use its official installation instructions at:<\/p>\n\n\n\n
    \nhttps:\/\/brew.sh\n<\/div><\/figure>\n\n\n\n
    The official installer command is:<\/p>\n\n\n
    \/bin\/bash -c \"$(curl -fsSL https:\/\/raw.githubusercontent.com\/Homebrew\/install\/HEAD\/install.sh)\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Review the script and follow the instructions displayed by the installer.<\/p>\n\n\n\n
    Step 4: Update Homebrew<\/h3>\n\n\n
    brew update<\/code><\/span><\/pre>\n\n\n
    Step 5: Install pre-commit<\/h3>\n\n\n
    brew install pre-commit<\/code><\/span><\/pre>\n\n\n
    Homebrew installs pre-commit and its required runtime dependencies.<\/p>\n\n\n\n
    Step 6: Verify Installation<\/h3>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n\n
    Expected output format:<\/p>\n\n\n
    pre-commit<\/span> 4.7<\/span>.0<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    The actual version depends on the version available through Homebrew.<\/p>\n\n\n\n
    Step 7: Locate the Executable<\/h3>\n\n\n
    which pre-commit<\/code><\/span><\/pre>\n\n\n
    Or:<\/p>\n\n\n
    command -v pre-commit<\/code><\/span><\/pre>\n\n\n
    Typical Apple Silicon Homebrew location:<\/p>\n\n\n
    \/opt\/homebrew\/bin\/pre-commit<\/code><\/span><\/pre>\n\n\n
    Typical Intel Homebrew location:<\/p>\n\n\n
    \/usr\/local\/bin\/pre-commit<\/code><\/span><\/pre>\n\n\n
    Step 8: Display Available Commands<\/h3>\n\n\n
    pre-commit --help<\/code><\/span><\/pre>\n\n\n
    pre-commit is now installed on macOS.<\/strong><\/p>\n\n\n\n
    Method 2: Install pre-commit Using pipx<\/h2>\n\n\n\n
    pipx is useful when you want to install Python command-line applications into isolated environments.<\/p>\n\n\n\n
    Step 1: Install pipx<\/h3>\n\n\n
    brew install pipx<\/code><\/span><\/pre>\n\n\n
    Step 2: Configure pipx PATH<\/h3>\n\n\n
    pipx ensurepath<\/code><\/span><\/pre>\n\n\n
    Open a new terminal if required.<\/p>\n\n\n\n
    Step 3: Install pre-commit<\/h3>\n\n\n
    pipx install pre-commit<\/code><\/span><\/pre>\n\n\n
    Step 4: Verify<\/h3>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n\n
    Using pipx keeps the pre-commit application separate from your project’s Python dependencies.<\/p>\n\n\n\n
    Method 3: Install pre-commit Using pip<\/h2>\n\n\n\n
    For a Python virtual environment:<\/p>\n\n\n
    python3<\/span> -m<\/span> venv<\/span> .venv<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Activate it:<\/p>\n\n\n
    source .venv\/bin\/activate<\/code><\/span><\/pre>\n\n\n
    Install pre-commit:<\/p>\n\n\n
    python -m pip install pre-commit<\/code><\/span><\/pre>\n\n\n
    Verify:<\/p>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n\n
    Recommendation:<\/strong> Use Homebrew or pipx for a general workstation installation. Use a project virtual environment when you intentionally manage pre-commit as a project dependency.<\/p>\n\n\n\n
    \n\n\n\n
    5. How to Install pre-commit on Windows 10\/11<\/h1>\n\n\n\n
    Windows users can install pre-commit using Python and pipx.<\/p>\n\n\n\n
    This method works with PowerShell, Windows Terminal, and compatible Git development environments.<\/p>\n\n\n\n
    Step 1: Open PowerShell<\/h2>\n\n\n\n
    Open Windows PowerShell or PowerShell 7.<\/p>\n\n\n\n
    Step 2: Check Python<\/h2>\n\n\n
    py --version<\/code><\/span><\/pre>\n\n\n
    Verify Python 3.11 or newer.<\/p>\n\n\n\n
    If Python is missing, download it from:<\/p>\n\n\n\n
    \nhttps:\/\/www.python.org\/downloads\/windows\n<\/div><\/figure>\n\n\n\n
    When installing, enable the option to add Python to PATH if offered.<\/p>\n\n\n\n
    Open a new PowerShell window after installation.<\/p>\n\n\n\n
    Verify pip<\/h3>\n\n\n
    py -m pip --version<\/code><\/span><\/pre>\n\n\n
    If pip is missing:<\/p>\n\n\n
    py -m ensurepip --upgrade<\/code><\/span><\/pre>\n\n\n
    Step 3: Install pipx<\/h2>\n\n\n\n
    Run:<\/p>\n\n\n
    py -m pip install --user pipx<\/code><\/span><\/pre>\n\n\n
    Configure its executable path:<\/p>\n\n\n
    py -m pipx ensurepath<\/code><\/span><\/pre>\n\n\n
    Close and reopen PowerShell.<\/p>\n\n\n\n
    Verify:<\/p>\n\n\n
    pipx --version<\/code><\/span><\/pre>\n\n\n
    Step 4: Install pre-commit<\/h2>\n\n\n
    pipx install pre-commit<\/code><\/span><\/pre>\n\n\n
    pipx creates an isolated Python environment for pre-commit and exposes its executable to your user account.<\/p>\n\n\n\n
    Step 5: Verify Installation<\/h2>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n\n
    Display help:<\/p>\n\n\n
    pre-commit --help<\/code><\/span><\/pre>\n\n\n
    Step 6: Locate the Executable<\/h2>\n\n\n
    Get-Command pre-commit<\/code><\/span><\/pre>\n\n\n
    Or:<\/p>\n\n\n
    where<\/span>.exe<\/span> pre-commit<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    This helps confirm which installation Windows is using.<\/p>\n\n\n\n
    pre-commit is now installed on Windows.<\/strong><\/p>\n\n\n\n
    Alternative: Install Through a Python Virtual Environment<\/h3>\n\n\n\n
    If you prefer a project-specific setup:<\/p>\n\n\n
    py<\/span> -m<\/span> venv<\/span> .venv<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Activate the environment:<\/p>\n\n\n
    .\\.venv<\/span>\\Scripts<\/span>\\Activate<\/span>.ps1<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Install:<\/p>\n\n\n
    python -m pip install pre-commit<\/code><\/span><\/pre>\n\n\n
    Verify:<\/p>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n\n
    If PowerShell blocks activation scripts because of an execution policy, you can invoke the environment’s Python directly:<\/p>\n\n\n
    .\\.venv<\/span>\\Scripts<\/span>\\python<\/span>.exe<\/span> -m<\/span> pip<\/span> install<\/span> pre-commit<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    And verify:<\/p>\n\n\n
    .\\.venv<\/span>\\Scripts<\/span>\\pre-commit<\/span>.exe<\/span> --version<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    This avoids modifying PowerShell’s execution policy.<\/p>\n\n\n\n
    Note:<\/strong> When Git invokes installed hooks, it must still be able to find the pre-commit executable. A user-wide pipx installation is often more convenient for Git hooks used across multiple projects.<\/p>\n\n\n\n
    \n\n\n\n
    6. How to Install pre-commit on Ubuntu and Debian<\/h1>\n\n\n\n
    For Ubuntu and Debian, pipx is a good installation choice because it avoids interfering with system-managed Python packages.<\/p>\n\n\n\n
    Step 1: Check Linux Distribution<\/h2>\n\n\n
    cat \/etc\/os-release<\/code><\/span><\/pre>\n\n\n
    Check Python:<\/p>\n\n\n
    python3 --version<\/code><\/span><\/pre>\n\n\n
    The current pre-commit version requires Python 3.11 or newer.<\/p>\n\n\n\n
    If your distribution’s default Python is older, install a supported Python release using your distribution’s approved repositories before continuing.<\/p>\n\n\n\n
    Step 2: Update Package Metadata<\/h2>\n\n\n
    sudo apt update<\/code><\/span><\/pre>\n\n\n
    Step 3: Install Dependencies<\/h2>\n\n\n
    sudo apt install -y \\\n  git \\\n  python3 \\\n  python3-pip \\\n  python3-venv \\\n  pipx<\/code><\/span><\/pre>\n\n\n
    Step 4: Configure pipx<\/h2>\n\n\n
    pipx ensurepath<\/code><\/span><\/pre>\n\n\n
    Start a new shell if necessary.<\/p>\n\n\n\n
    Step 5: Install pre-commit<\/h2>\n\n\n
    pipx install pre-commit<\/code><\/span><\/pre>\n\n\n
    Step 6: Verify Installation<\/h2>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n\n
    Check executable location:<\/p>\n\n\n
    command -v pre-commit<\/code><\/span><\/pre>\n\n\n
    Display help:<\/p>\n\n\n
    pre-commit --help<\/code><\/span><\/pre>\n\n\n
    The installation is complete.<\/p>\n\n\n\n
    Alternative: Install pre-commit with APT<\/h3>\n\n\n\n
    Some Debian-based distributions provide a pre-commit package through their repositories:<\/p>\n\n\n
    sudo apt install pre-commit<\/code><\/span><\/pre>\n\n\n
    However, the distribution package may be older than the current upstream release.<\/p>\n\n\n\n
    Check:<\/p>\n\n\n
    apt-cache policy pre-commit<\/code><\/span><\/pre>\n\n\n
    For the current upstream release, pipx is generally preferable.<\/p>\n\n\n\n
    Alternative: Install Using pip in a Virtual Environment<\/h3>\n\n\n\n
    Create an isolated environment:<\/p>\n\n\n
    python3 -m venv ~\/.venvs\/<\/span>pre-commit<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Install:<\/p>\n\n\n
    ~\/.venvs\/<\/span>pre-commit\/bin\/python -m pip install pre-commit<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Verify:<\/p>\n\n\n
    ~\/.venvs\/<\/span>pre-commit\/bin\/pre-commit --version<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    To use this executable globally, you can create a symbolic link in a user-local bin directory:<\/p>\n\n\n
    mkdir -p ~\/.local\/<\/span>bin<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n
    ln -s ~\/.venvs\/<\/span>pre-commit\/bin\/pre-commit ~\/.local\/<\/span>bin\/pre-commit<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Ensure ~\/.local\/bin<\/code> is included in your PATH.<\/p>\n\n\n\n
    This approach also avoids modifying system Python packages.<\/p>\n\n\n\n
    \n\n\n\n
    7. How to Install pre-commit on Fedora, RHEL, CentOS, and Rocky Linux<\/h1>\n\n\n\n
    On Fedora, pipx can generally be installed using DNF.<\/p>\n\n\n\n
    For RHEL and compatible distributions where pipx is unavailable in the enabled repositories, a Python virtual environment is a useful alternative.<\/p>\n\n\n\n
    Method 1: Fedora Installation Using pipx<\/h2>\n\n\n\n
    Step 1: Install Dependencies<\/h3>\n\n\n
    sudo dnf install -y \\\n  git \\\n  python3 \\\n  python3-pip \\\n  pipx<\/code><\/span><\/pre>\n\n\n
    Step 2: Configure pipx<\/h3>\n\n\n
    pipx ensurepath<\/code><\/span><\/pre>\n\n\n
    Open a new terminal.<\/p>\n\n\n\n
    Step 3: Install pre-commit<\/h3>\n\n\n
    pipx install pre-commit<\/code><\/span><\/pre>\n\n\n
    Step 4: Verify Installation<\/h3>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n\n
    Method 2: RHEL\/CentOS Installation Using a Virtual Environment<\/h2>\n\n\n\n
    Step 1: Install Git and a Compatible Python Runtime<\/h3>\n\n\n\n
    For systems with appropriate package repositories enabled:<\/p>\n\n\n
    sudo dnf install -y git python3 python3-pip<\/code><\/span><\/pre>\n\n\n
    Check:<\/p>\n\n\n
    python3 --version<\/code><\/span><\/pre>\n\n\n
    If the default Python is older than 3.11, install a supported newer version and use that interpreter for the following commands.<\/p>\n\n\n\n
    Step 2: Create a Virtual Environment<\/h3>\n\n\n
    python3 -m venv ~\/.venvs\/<\/span>pre-commit<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Step 3: Install pre-commit<\/h3>\n\n\n
    ~\/.venvs\/<\/span>pre-commit\/bin\/python -m pip install pre-commit<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Step 4: Configure a Command Path<\/h3>\n\n\n
    mkdir -p ~\/.local\/<\/span>bin<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n
    ln -s ~\/.venvs\/<\/span>pre-commit\/bin\/pre-commit ~\/.local\/<\/span>bin\/pre-commit<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Add it to Bash’s PATH if required:<\/p>\n\n\n
    echo<\/span> 'export PATH=\"$HOME\/.local\/bin:$PATH\"'<\/span> >> ~\/.bashrc<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    Reload:<\/p>\n\n\n
    source ~\/.bashrc<\/code><\/span><\/pre>\n\n\n
    Step 5: Verify Installation<\/h3>\n\n\n
    pre-commit --version<\/code><\/span><\/pre>\n\n
    pre-commit --help<\/code><\/span><\/pre>\n\n\n
    Important:<\/strong> Available Python versions and package names vary across RHEL, CentOS Stream, Rocky Linux, and other RPM-based distributions. Do not replace the system Python interpreter merely to install pre-commit.<\/p>\n\n\n\n
    \n\n\n\n
    8. Configure pre-commit in a Git Repository<\/h1>\n\n\n\n
    Installing the pre-commit application is only the first part of the setup.<\/p>\n\n\n\n
    You must also configure the hooks for each Git repository where you want them to run.<\/p>\n\n\n\n
    The following steps are the same on macOS, Windows, and Linux.<\/p>\n\n\n\n
    Step 1: Navigate to Your Git Repository<\/h2>\n\n\n\n
    For an existing repository:<\/p>\n\n\n
    cd \/path\/to\/your\/project<\/code><\/span><\/pre>\n\n\n
    On Windows PowerShell, an example is:<\/p>\n\n\n
    cd C:\\Projects\\my-app<\/code><\/span><\/pre>\n\n\n
    If you want to create a new demonstration repository:<\/p>\n\n\n
    mkdir pre-commit-demo\ncd pre-commit-demo\ngit init<\/code><\/span><\/pre>\n\n\n
    Verify that you are inside a Git repository:<\/p>\n\n\n
    git status<\/code><\/span><\/pre>\n\n\n
    If Git displays repository status information, continue.<\/p>\n\n\n\n
    Step 2: Create the pre-commit Configuration File<\/h2>\n\n\n\n
    pre-commit reads its configuration from:<\/p>\n\n\n
    .pre-commit-config<\/span>.yaml<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    The file must be placed in the root of your Git repository.<\/p>\n\n\n\n
    You can create a starter configuration using:<\/p>\n\n\n
    pre-commit sample-config<\/code><\/span><\/pre>\n\n\n
    To save the generated configuration directly on macOS or Linux:<\/p>\n\n\n
    pre-commit<\/span> sample-config<\/span> > .pre-commit-config<\/span>.yaml<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    On Windows, you can create or edit the file using VS Code:<\/p>\n\n\n
    code<\/span> .pre-commit-config<\/span>.yaml<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Alternatively:<\/p>\n\n\n
    notepad<\/span> .pre-commit-config<\/span>.yaml<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    If the file does not exist, create it when prompted.<\/p>\n\n\n\n
    Step 3: Add a Practical Configuration<\/h2>\n\n\n\n
    For a typical project, use the following configuration:<\/p>\n\n\n
    # .pre-commit-config.yaml<\/span>\n\nminimum_pre_commit_version: \"4.0.0\"<\/span>\n\nrepos:\n  - repo: https:\/\/github.com\/pre-commit\/pre-commit-hooks<\/span>\n    rev: v6.0<\/span>.0<\/span>\n    hooks:\n      - id: trailing-whitespace\n\n      - id: end-of-file-fixer\n\n      - id: check-yaml\n\n      - id: check-json\n\n      - id: check-toml\n\n      - id: check-merge-conflict\n\n      - id: check-case<\/span>-conflict\n\n      - id: detect-private<\/span>-key\n\n      - id: check-added-large-files\n        args: [--maxkb=1024<\/span>]<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    This is a language-neutral configuration suitable for many software projects.<\/p>\n\n\n\n
    Understanding the Configuration<\/h3>\n\n\n\n
    Setting<\/th>Purpose<\/th><\/tr>
    minimum_pre_commit_version<\/code><\/td>Enforces a minimum supported framework version<\/td><\/tr>
    repos<\/code><\/td>Lists hook repositories<\/td><\/tr>
    repo<\/code><\/td>Repository URL containing hooks<\/td><\/tr>
    rev<\/code><\/td>Version, tag, or commit to use<\/td><\/tr>
    hooks<\/code><\/td>Hooks enabled from that repository<\/td><\/tr>
    id<\/code><\/td>Identifier of a particular hook<\/td><\/tr>
    args<\/code><\/td>Additional command-line arguments<\/td><\/tr>
    files<\/code><\/td>Regex matching files the hook should process<\/td><\/tr>
    exclude<\/code><\/td>Regex excluding files from processing<\/td><\/tr>
    stages<\/code><\/td>Git hook stages on which a hook should run<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    What Do These Hooks Check?<\/h3>\n\n\n\n
    Hook<\/th>Function<\/th><\/tr>
    trailing-whitespace<\/code><\/td>Removes trailing whitespace<\/td><\/tr>
    end-of-file-fixer<\/code><\/td>Ensures a consistent final newline<\/td><\/tr>
    check-yaml<\/code><\/td>Checks YAML syntax<\/td><\/tr>
    check-json<\/code><\/td>Checks JSON syntax<\/td><\/tr>
    check-toml<\/code><\/td>Checks TOML syntax<\/td><\/tr>
    check-merge-conflict<\/code><\/td>Detects common unresolved merge conflict markers<\/td><\/tr>
    check-case-conflict<\/code><\/td>Detects filenames that conflict on case-insensitive filesystems<\/td><\/tr>
    detect-private-key<\/code><\/td>Detects certain private-key patterns<\/td><\/tr>
    check-added-large-files<\/code><\/td>Prevents staged additions exceeding the configured size limit<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    In this example, --maxkb=1024<\/code> sets the added-file limit to 1,024 KB.<\/p>\n\n\n\n
    Security note:<\/strong> detect-private-key<\/code> is not a comprehensive secret scanner. Consider a dedicated secret-scanning tool for broader credential detection.<\/p>\n\n\n\n
    Step 4: Validate the Configuration<\/h2>\n\n\n\n
    Run:<\/p>\n\n\n
    pre-commit validate-config<\/code><\/span><\/pre>\n\n\n
    If the command exits successfully without errors, the configuration is syntactically valid according to pre-commit’s configuration schema.<\/p>\n\n\n\n
    Step 5: Install the Git Hook<\/h2>\n\n\n\n
    Execute:<\/p>\n\n\n
    pre-commit install<\/code><\/span><\/pre>\n\n\n
    Example output:<\/p>\n\n\n
    pre-commit installed at .git\/hooks\/pre-commit<\/code><\/span><\/pre>\n\n\n
    This installs the Git hook launcher for the current repository.<\/p>\n\n\n\n
    From this point onward, a normal git commit<\/code> triggers configured pre-commit-stage hooks.<\/p>\n\n\n\n
    Important:<\/strong> This step is repository-specific. Every developer must install the hook in their local clone, unless their development environment already provides equivalent setup automation.<\/p>\n\n\n\n
    Step 6: Download and Prepare Hook Environments<\/h2>\n\n\n\n
    You can initialize hook environments before your first commit:<\/p>\n\n\n
    pre-commit install-hooks<\/code><\/span><\/pre>\n\n\n
    This downloads and prepares the required hook environments.<\/p>\n\n\n\n
    The initial run may take longer because hook dependencies must be installed.<\/p>\n\n\n\n
    Subsequent runs can reuse cached environments.<\/p>\n\n\n\n
    Step 7: Run Hooks Against All Files<\/h2>\n\n\n\n
    Execute:<\/p>\n\n\n
    pre-commit run --all-files<\/code><\/span><\/pre>\n\n\n
    This checks applicable Git-tracked files in the repository.<\/p>\n\n\n\n
    Example output:<\/p>\n\n\n
    Trim<\/span> Trailing<\/span> Whitespace<\/span>........................Passed<\/span>\nFix<\/span> End<\/span> of<\/span> Files<\/span>................................Passed<\/span>\nCheck<\/span> Yaml<\/span>......................................Passed<\/span>\nCheck<\/span> JSON<\/span>......................................Passed<\/span>\nCheck<\/span> Toml<\/span>......................................Passed<\/span>\nCheck<\/span> for<\/span> merge<\/span> conflicts<\/span>.......................Passed<\/span>\nCheck<\/span> for<\/span> case<\/span> conflicts<\/span>.........................Passed<\/span>\nDetect<\/span> Private<\/span> Key<\/span>.............................Passed<\/span>\nCheck<\/span> for<\/span> added<\/span> large<\/span> files<\/span>.....................Passed<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    The exact output depends on the files in your repository.<\/p>\n\n\n\n
    A hook may report Skipped<\/code> when no files match its conditions.<\/p>\n\n\n\n
    \n\n\n\n
    9. Test pre-commit with a Real Git Commit<\/h1>\n\n\n\n
    Now let’s confirm that pre-commit runs automatically.<\/p>\n\n\n\n
    Step 1: Create a Sample File<\/h2>\n\n\n\n
    On macOS\/Linux:<\/p>\n\n\n
    printf 'name: demo\\n'<\/span> > example.yaml<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    On Windows PowerShell:<\/p>\n\n\n
    Set<\/span>-Content -Path example.yaml -Value \"name: demo\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Step 2: Stage the Files<\/h2>\n\n\n
    git<\/span> add<\/span> .pre-commit-config<\/span>.yaml<\/span> example<\/span>.yaml<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Step 3: Create a Commit<\/h2>\n\n\n
    git commit -m \"Add pre-commit configuration\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Before creating the commit, Git invokes the installed pre-commit hook.<\/p>\n\n\n\n
    If all checks pass, Git continues creating the commit.<\/p>\n\n\n\n
    If a check fails, the commit is normally blocked.<\/p>\n\n\n\n
    If the hook automatically fixes a file, review and stage the updated file before retrying.<\/p>\n\n\n\n
    For example:<\/p>\n\n\n
    git status<\/code><\/span><\/pre>\n\n
    git diff<\/code><\/span><\/pre>\n\n\n
    Then:<\/p>\n\n\n
    git<\/span> add<\/span> example<\/span>.yaml<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Retry:<\/p>\n\n\n
    git commit -m \"Add pre-commit configuration\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    If Git reports that your author identity is not configured, follow Git’s instructions to set user.name<\/code> and user.email<\/code> before retrying.<\/p>\n\n\n\n
    \n\n\n\n
    10. Essential pre-commit Commands<\/h1>\n\n\n\n
    The following commands are useful for everyday development.<\/p>\n\n\n\n
    Command<\/th>Purpose<\/th><\/tr>
    pre-commit --version<\/code><\/td>Display installed version<\/td><\/tr>
    pre-commit --help<\/code><\/td>Show available commands<\/td><\/tr>
    pre-commit sample-config<\/code><\/td>Generate a sample configuration<\/td><\/tr>
    pre-commit validate-config<\/code><\/td>Validate configuration syntax<\/td><\/tr>
    pre-commit install<\/code><\/td>Install Git hook launcher<\/td><\/tr>
    pre-commit install-hooks<\/code><\/td>Prepare hook environments<\/td><\/tr>
    pre-commit run<\/code><\/td>Run applicable hooks on staged files<\/td><\/tr>
    pre-commit run --all-files<\/code><\/td>Run applicable hooks on all tracked files<\/td><\/tr>
    pre-commit run check-yaml --all-files<\/code><\/td>Run one specific hook<\/td><\/tr>
    pre-commit run --files example.yaml<\/code><\/td>Run applicable hooks on one file<\/td><\/tr>
    pre-commit autoupdate<\/code><\/td>Update hook repository revisions<\/td><\/tr>
    pre-commit clean<\/code><\/td>Remove cached hook environments<\/td><\/tr>
    pre-commit gc<\/code><\/td>Remove unused cached repositories<\/td><\/tr>
    pre-commit uninstall<\/code><\/td>Remove installed Git hook launcher<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Run a Specific Hook<\/h2>\n\n\n
    pre-commit run trailing-whitespace --all-files<\/code><\/span><\/pre>\n\n\n
    Validate Only YAML Files<\/h2>\n\n\n
    pre-commit run check-yaml --all-files<\/code><\/span><\/pre>\n\n\n
    Run Against Specific Files<\/h2>\n\n\n
    pre-commit<\/span> run<\/span> --files<\/span> README<\/span>.md<\/span> example<\/span>.yaml<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    Display More Information on Failed Hooks<\/h2>\n\n\n
    pre-commit run --all-files --verbose<\/code><\/span><\/pre>\n\n\n
    Show Diffs When Hooks Modify Files<\/h2>\n\n\n
    pre-commit run --all-files --show-diff-on-failure<\/code><\/span><\/pre>\n\n\n
    This is particularly useful in CI\/CD pipelines.<\/p>\n\n\n\n
    \n\n\n\n
    11. Configure pre-commit for Python Projects<\/h1>\n\n\n\n
    Python projects can use pre-commit to execute formatters and linters automatically.<\/p>\n\n\n\n
    Ruff provides Python linting and formatting functionality.<\/p>\n\n\n\n
    To configure Ruff, add the following repository to your existing .pre-commit-config.yaml<\/code>:<\/p>\n\n\n\n
      - repo: https:\/\/github.com\/astral-sh\/ruff-pre-commit\n    rev: v0.16.10\n    hooks:\n      - id: ruff-check\n        args: [--fix]\n\n      - id: ruff-format<\/code><\/pre>\n\n\n\n
    The version above is an example of a published Ruff hook release. Keep its pinned version aligned with the Ruff configuration and compatibility requirements of your project.<\/p>\n\n\n\n
    What Happens?<\/h3>\n\n\n\n
    When Python files are committed:<\/p>\n\n\n\n
      \n
    1. Ruff checks the Python code.<\/li>\n\n\n\n
    2. Ruff applies supported automatic lint fixes.<\/li>\n\n\n\n
    3. Ruff formats the code.<\/li>\n\n\n\n
    4. pre-commit reports failures or modified files.<\/li>\n\n\n\n
    5. The developer reviews and stages any changes.<\/li>\n<\/ol>\n\n\n\n
      Run manually:<\/p>\n\n\n
      pre-commit run ruff-check --all-files<\/code><\/span><\/pre>\n\n\n
      Format all applicable tracked Python files:<\/p>\n\n\n
      pre-commit run ruff-format --all-files<\/code><\/span><\/pre>\n\n\n
      Recommendation:<\/strong> Keep the Ruff linting hook before the formatting hook when enabling --fix<\/code>.<\/p>\n\n\n\n
      \n\n\n\n
      12. Configure pre-commit for Terraform Projects<\/h1>\n\n\n\n
      For Infrastructure-as-Code projects, pre-commit can help maintain consistent Terraform formatting and perform additional checks.<\/p>\n\n\n\n
      A popular hook collection is:<\/p>\n\n\n\n
      \nhttps:\/\/github.com\/antonbabenko\/pre-commit-terraform\n<\/div><\/figure>\n\n\n\n
      Add the following to your configuration:<\/p>\n\n\n\n
        - repo: https:\/\/github.com\/antonbabenko\/pre-commit-terraform\n    rev: v1.108.1\n    hooks:\n      - id: terraform_fmt<\/code><\/pre>\n\n\n\n
      This example enables Terraform formatting.<\/p>\n\n\n\n
      Run Terraform Formatting<\/h3>\n\n\n
      pre-commit run terraform_fmt --all-files<\/code><\/span><\/pre>\n\n\n
      Add Terraform Validation<\/h3>\n\n\n\n
      If your project needs additional Terraform validation, you can add:<\/p>\n\n\n\n
            - id: terraform_validate<\/code><\/pre>\n\n\n\n
      However, Terraform validation may require initialized working directories, provider plugins, module downloads, and suitable backend configuration.<\/p>\n\n\n\n
      Terraform and other required supporting tools must be available for these hooks.<\/p>\n\n\n\n
      For Windows users, WSL is often a practical environment for shell-oriented Terraform pre-commit hook integrations.<\/p>\n\n\n\n
      Best practice:<\/strong> Run fast formatting checks before commits, and place more expensive Terraform validation, linting, and security checks in CI\/CD when appropriate.<\/p>\n\n\n\n
      \n\n\n\n
      13. Configure Different Git Hook Stages<\/h1>\n\n\n\n
      pre-commit can manage more than the standard pre-commit<\/code> Git hook.<\/p>\n\n\n\n
      It supports stages such as:<\/p>\n\n\n\n
        \n
      • pre-commit<\/code><\/li>\n\n\n\n
      • pre-push<\/code><\/li>\n\n\n\n
      • commit-msg<\/code><\/li>\n\n\n\n
      • pre-merge-commit<\/code><\/li>\n\n\n\n
      • post-checkout<\/code><\/li>\n\n\n\n
      • post-merge<\/code><\/li>\n<\/ul>\n\n\n\n
        Example: Install Both pre-commit and pre-push Hooks<\/h2>\n\n\n
        pre-commit install \\\n  --hook-type pre-commit \\\n  --hook-type pre-push<\/code><\/span><\/pre>\n\n\n
        For Windows PowerShell, use one line:<\/p>\n\n\n
        pre-commit install --hook-type pre-commit --hook-type pre-push<\/code><\/span><\/pre>\n\n\n
        You can specify hook stages in your configuration.<\/p>\n\n\n\n
        For example:<\/p>\n\n\n
        default_install_hook_types:\n  - pre-commit\n  - pre-push\n\nrepos<\/span>:\n  - repo: https:\/\/github.com\/pre-commit\/pre-commit-hooks<\/span>\n    rev: v6.0<\/span>.0<\/span>\n    hooks<\/span>:\n      - id: trailing-whitespace\n        stages<\/span>: [pre-commit]\n\n      - id: check-yaml\n        stages<\/span>: [pre-commit, pre-push]<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
        With this configuration:<\/p>\n\n\n\n
          \n
        • Trailing whitespace checks run before commits.<\/li>\n\n\n\n
        • YAML validation runs before commits and pushes.<\/li>\n<\/ul>\n\n\n\n
          A git push<\/code> will trigger the installed pre-push hook.<\/p>\n\n\n\n
          Remember that a hook’s configured stages and the Git hook launchers installed in the repository must both be correct for it to run automatically.<\/p>\n\n\n\n
          \n\n\n\n
          14. Exclude Files and Directories from pre-commit<\/h1>\n\n\n\n
          Some files should not be formatted or checked automatically.<\/p>\n\n\n\n
          Common examples include:<\/p>\n\n\n\n
            \n
          • Generated files.<\/li>\n\n\n\n
          • Build outputs.<\/li>\n\n\n\n
          • Dependency directories.<\/li>\n\n\n\n
          • Large vendor directories.<\/li>\n\n\n\n
          • Compiled artifacts.<\/li>\n<\/ul>\n\n\n\n
            You can exclude paths using regular expressions.<\/p>\n\n\n\n
            Example:<\/p>\n\n\n
            exclude: |\n  (?x)^(\n    node_modules\/|\n    dist\/|\n    build\/|\n    vendor\/|\n    coverage\/|\n    \\.venv\/|\n    \\.terraform\/\n  )<\/code><\/span><\/pre>\n\n\n
            Add this at the top level of .pre-commit-config.yaml<\/code>.<\/p>\n\n\n\n
            For individual hooks:<\/p>\n\n\n
            repos:\n  - repo: https:\/\/github.com\/pre-commit\/pre-commit-hooks<\/span>\n    rev: v6.0<\/span>.0<\/span>\n    hooks<\/span>:\n      - id: trailing-whitespace\n        exclude<\/span>: ^generated\/<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
            This excludes files under generated\/<\/code> from that specific hook.<\/p>\n\n\n\n
            Important:<\/strong> Exclusions use regular expressions and apply to the files pre-commit considers. They are not identical to .gitignore<\/code> patterns.<\/p>\n\n\n\n
            \n\n\n\n
            15. Run pre-commit Automatically in GitHub Actions<\/h1>\n\n\n\n
            Local Git hooks are useful, but developers can skip them or forget to install them.<\/p>\n\n\n\n
            For consistent team enforcement, run the same checks in CI\/CD.<\/p>\n\n\n\n
            GitHub Actions is one option.<\/p>\n\n\n\n
            Step 1: Create the Workflow Directory<\/h2>\n\n\n\n
            On macOS\/Linux:<\/p>\n\n\n
            mkdir -p .github\/workflows<\/code><\/span><\/pre>\n\n\n
            On Windows PowerShell:<\/p>\n\n\n
            New<\/span>-Item -ItemType Directory -Force -Path .github\/workflows<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
            Step 2: Create a Workflow File<\/h2>\n\n\n\n
            Create:<\/p>\n\n\n
            .github\/workflows\/pre-commit.yml<\/code><\/span><\/pre>\n\n\n
            Add:<\/p>\n\n\n
            name: Pre-commit Checks\n\non<\/span>:\n  push:\n  pull_request:\n\npermissions:\n  contents: read\n\njobs<\/span>:\n  pre-commit:\n    runs-on: ubuntu-latest\n\n    steps<\/span>:\n      - name: Checkout repository\n        uses<\/span>: actions\/checkout@v7\n\n      - name: Set<\/span> up Python\n        uses<\/span>: actions\/setup-python@v7\n        with<\/span>:\n          python-version: \"3.13\"<\/span>\n\n      - name: Install pre-commit\n        run<\/span>: python -m pip install pre-commit==4.7<\/span>.0<\/span>\n\n      - name: Validate configuration\n        run<\/span>: pre-commit validate-config\n\n      - name: Run all hooks\n        run<\/span>: pre-commit run --all-files --show-diff-on-failure<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
            This workflow:<\/p>\n\n\n\n
              \n
            1. Checks out the repository.<\/li>\n\n\n\n
            2. Configures Python.<\/li>\n\n\n\n
            3. Installs the specified pre-commit version.<\/li>\n\n\n\n
            4. Validates the configuration.<\/li>\n\n\n\n
            5. Executes configured hooks against applicable tracked files.<\/li>\n<\/ol>\n\n\n\n
              If a hook fails or modifies a file, the GitHub Actions job fails, allowing the developer to review the issue.<\/p>\n\n\n\n
              For stricter software supply-chain controls, pin GitHub Actions to reviewed commit SHAs and restrict the permissions available to workflow jobs.<\/p>\n\n\n\n
              Optional: Test Across Multiple Operating Systems<\/h3>\n\n\n\n
              To verify cross-platform behavior, use:<\/p>\n\n\n
              strategy:\n  matrix:\n    os:\n      - ubuntu-latest\n      - windows-latest\n      - macos-latest\n\nruns-on: ${{ matrix.os }}<\/code><\/span><\/pre>\n\n\n
              Add this matrix to the job and use the matrix variable instead of a single runs-on<\/code> value.<\/p>\n\n\n\n
              Running checks in CI\/CD helps ensure that contributors receive consistent results even when local hooks are missing.<\/p>\n\n\n\n
              \n\n\n\n
              16. How to Update pre-commit<\/h1>\n\n\n\n
              There are two different kinds of updates:<\/p>\n\n\n\n
                \n
              1. Updating the pre-commit framework.<\/li>\n\n\n\n
              2. Updating hook versions in .pre-commit-config.yaml<\/code>.<\/li>\n<\/ol>\n\n\n\n
                These are separate operations.<\/p>\n\n\n\n
                Update pre-commit on macOS<\/h2>\n\n\n\n
                Homebrew:<\/p>\n\n\n
                brew update\nbrew upgrade pre-commit<\/code><\/span><\/pre>\n\n\n
                pipx:<\/p>\n\n\n
                pipx upgrade pre-commit<\/code><\/span><\/pre>\n\n\n
                Update pre-commit on Windows<\/h2>\n\n\n\n
                For a pipx installation:<\/p>\n\n\n
                pipx upgrade pre-commit<\/code><\/span><\/pre>\n\n\n
                Update pre-commit on Linux<\/h2>\n\n\n\n
                For a pipx installation:<\/p>\n\n\n
                pipx upgrade pre-commit<\/code><\/span><\/pre>\n\n\n
                For a virtual-environment installation:<\/p>\n\n\n
                ~\/.venvs\/<\/span>pre-commit\/bin\/python -m pip install --upgrade pre-commit<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                Update Configured Hook Versions<\/h3>\n\n\n\n
                Run:<\/p>\n\n\n
                pre-commit autoupdate<\/code><\/span><\/pre>\n\n\n
                This updates the hook repository revisions in .pre-commit-config.yaml<\/code> to newer available versions.<\/p>\n\n\n\n
                After updating, run:<\/p>\n\n\n
                pre-commit validate-config<\/code><\/span><\/pre>\n\n\n
                Then:<\/p>\n\n\n
                pre-commit run --all-files<\/code><\/span><\/pre>\n\n\n
                Review the resulting changes before committing them.<\/p>\n\n\n\n
                Production recommendation:<\/strong> Avoid automatically accepting every hook upgrade. Review release notes and compatibility changes before rolling updated hooks out to a team.<\/p>\n\n\n\n
                \n\n\n\n
                17. Troubleshooting Common pre-commit Errors<\/h1>\n\n\n\n
                The following table summarizes common installation and configuration problems.<\/p>\n\n\n\n
                Error or symptom<\/th>Possible cause<\/th>Recommended solution<\/th><\/tr>
                pre-commit: command not found<\/code><\/td>Executable missing from PATH<\/td>Verify installation and PATH<\/td><\/tr>
                pre-commit is not recognized<\/code><\/td>Windows PATH not refreshed<\/td>Restart PowerShell and check installation<\/td><\/tr>
                No .pre-commit-config.yaml file was found<\/code><\/td>Configuration file missing<\/td>Create the file in the repository root<\/td><\/tr>
                InvalidConfigError<\/code><\/td>Incorrect YAML or configuration format<\/td>Run pre-commit validate-config<\/code><\/td><\/tr>
                git failed<\/code><\/td>Git unavailable or repository problem<\/td>Verify Git and repository status<\/td><\/tr>
                externally-managed-environment<\/code><\/td>System Python managed by OS<\/td>Use pipx or a virtual environment<\/td><\/tr>
                Permission denied<\/code><\/td>Installation or execution permissions<\/td>Check executable permissions<\/td><\/tr>
                Failed to create environment<\/code><\/td>Python\/runtime\/dependency issue<\/td>Check required runtime and hook dependencies<\/td><\/tr>
                Files were modified by this hook<\/code><\/td>Formatter changed files<\/td>Review and stage changes again<\/td><\/tr>
                An unexpected error has occurred<\/code><\/td>Hook installation or execution failure<\/td>Inspect detailed output and pre-commit log<\/td><\/tr>
                Hook never runs on commit<\/td>Git launcher not installed or custom hooks path<\/td>Reinstall and inspect Git hook configuration<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                Troubleshooting 1: pre-commit Command Not Found<\/h2>\n\n\n\n
                On macOS\/Linux:<\/p>\n\n\n
                command -v pre-commit<\/code><\/span><\/pre>\n\n\n
                Check:<\/p>\n\n\n
                echo<\/span> \"$PATH\"<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                For a pipx installation:<\/p>\n\n\n
                pipx list<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                Run:<\/p>\n\n\n
                pipx ensurepath<\/code><\/span><\/pre>\n\n\n
                Open a new terminal and retry.<\/p>\n\n\n\n
                Troubleshooting 2: pre-commit Not Recognized on Windows<\/h2>\n\n\n\n
                Check:<\/p>\n\n\n
                Get-Command pre-commit<\/code><\/span><\/pre>\n\n\n
                Inspect pipx installations:<\/p>\n\n\n
                pipx list<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                Refresh PATH configuration:<\/p>\n\n\n
                py -m pipx ensurepath<\/code><\/span><\/pre>\n\n\n
                Open a new PowerShell window.<\/p>\n\n\n\n
                Troubleshooting 3: Invalid Configuration<\/h2>\n\n\n\n
                Example:<\/p>\n\n\n
                InvalidConfigError:\n==> File .pre-commit-config.yaml<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                Check the YAML syntax and configuration schema.<\/p>\n\n\n\n
                Run:<\/p>\n\n\n
                pre-commit validate-config<\/code><\/span><\/pre>\n\n\n
                Common mistakes include:<\/p>\n\n\n\n
                  \n
                • Incorrect indentation.<\/li>\n\n\n\n
                • Missing repos<\/code> entries.<\/li>\n\n\n\n
                • Invalid hook IDs.<\/li>\n\n\n\n
                • Invalid stage names.<\/li>\n\n\n\n
                • Incorrect YAML list formatting.<\/li>\n\n\n\n
                • Unsupported configuration properties.<\/li>\n<\/ul>\n\n\n\n
                  Troubleshooting 4: Python Version Not Supported<\/h2>\n\n\n\n
                  Verify:<\/p>\n\n\n
                  python3 --version<\/code><\/span><\/pre>\n\n\n
                  Or on Windows:<\/p>\n\n\n
                  py --version<\/code><\/span><\/pre>\n\n\n
                  pre-commit 4.7.0 requires Python 3.11 or newer.<\/p>\n\n\n\n
                  Install or select a compatible Python runtime, then reinstall pre-commit using that runtime.<\/p>\n\n\n\n
                  Hook environments can have additional language-version requirements of their own.<\/p>\n\n\n\n
                  Troubleshooting 5: Files Were Modified by This Hook<\/h2>\n\n\n\n
                  Example output:<\/p>\n\n\n
                  Trim Trailing Whitespace................Failed\n- hook id: trailing-whitespace\n- exit code: 1<\/span>\n- files were modified by this<\/span> hook<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                  This does not necessarily mean the tool is broken.<\/p>\n\n\n\n
                  The hook may have successfully fixed a formatting problem and intentionally stopped the commit.<\/p>\n\n\n\n
                  Review the changes:<\/p>\n\n\n
                  git diff<\/code><\/span><\/pre>\n\n\n
                  Stage the modified files:<\/p>\n\n\n
                  git add .<\/code><\/span><\/pre>\n\n\n
                  Run checks again:<\/p>\n\n\n
                  pre-commit run --all-files<\/code><\/span><\/pre>\n\n\n
                  Then retry the commit.<\/p>\n\n\n\n
                  When working in an existing repository, stage only the files you intend to commit instead of using git add .<\/code> indiscriminately.<\/p>\n\n\n\n
                  Troubleshooting 6: pre-commit Does Not Execute During Git Commit<\/h2>\n\n\n\n
                  Check the Git hooks path:<\/p>\n\n\n
                  git config --get<\/span> core.hooksPath<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                  A custom hooks directory may cause Git to ignore the normal .git\/hooks<\/code> directory.<\/p>\n\n\n\n
                  Reinstall the launcher:<\/p>\n\n\n
                  pre-commit install<\/code><\/span><\/pre>\n\n\n
                  If the repository uses a custom core.hooksPath<\/code>, integrate pre-commit with that existing hook-management approach rather than overwriting another tool’s configuration without review.<\/p>\n\n\n\n
                  Troubleshooting 7: Clear Broken Hook Environments<\/h2>\n\n\n\n
                  If a cached hook environment appears corrupted, run:<\/p>\n\n\n
                  pre-commit clean<\/code><\/span><\/pre>\n\n\n
                  Then:<\/p>\n\n\n
                  pre-commit install-hooks<\/code><\/span><\/pre>\n\n\n
                  Finally:<\/p>\n\n\n
                  pre-commit run --all-files<\/code><\/span><\/pre>\n\n\n
                  This forces the required hook environments to be rebuilt.<\/p>\n\n\n\n
                  Do not treat cache clearing as a fix for invalid credentials, unavailable dependencies, or broken configuration files.<\/p>\n\n\n\n
                  \n\n\n\n
                  18. How to Temporarily Skip pre-commit Hooks<\/h1>\n\n\n\n
                  Occasionally, a developer may need to skip a particular hook for a legitimate reason.<\/p>\n\n\n\n
                  pre-commit supports the SKIP<\/code> environment variable.<\/p>\n\n\n\n
                  macOS\/Linux<\/h3>\n\n\n\n
                  For example:<\/p>\n\n\n
                  SKIP=check-yaml git commit -m \"Temporary commit\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                  This skips only the configured hook with the specified ID.<\/p>\n\n\n\n
                  Windows PowerShell<\/h3>\n\n\n
                  $env:SKIP = \"check-yaml\"<\/span>\n\ngit commit -m \"Temporary commit\"<\/span>\n\nRemove-Item Env:\\SKIP<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                  Skip All Git Commit Verification Hooks<\/h3>\n\n\n\n
                  Git also supports:<\/p>\n\n\n
                  git commit --no-verify -m \"Temporary commit\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                  However, this bypasses applicable Git commit verification hooks, not just a single pre-commit check.<\/p>\n\n\n\n
                  Best practice:<\/strong> Avoid bypassing checks except for clearly justified situations. CI\/CD should independently enforce the project’s required checks.<\/p>\n\n\n\n
                  \n\n\n\n
                  19. How to Uninstall pre-commit<\/h1>\n\n\n\n
                  If you want to remove pre-commit from a repository, first remove the Git hook launcher.<\/p>\n\n\n\n
                  Navigate to the repository:<\/p>\n\n\n
                  cd \/path\/to\/your\/project<\/code><\/span><\/pre>\n\n\n
                  Execute:<\/p>\n\n\n
                  pre-commit uninstall<\/code><\/span><\/pre>\n\n\n
                  This removes the installed pre-commit Git hook launcher.<\/p>\n\n\n\n
                  You can then remove the application using the package manager that installed it.<\/p>\n\n\n\n
                  macOS \u2014 Homebrew<\/h3>\n\n\n
                  brew uninstall pre-commit<\/code><\/span><\/pre>\n\n\n
                  macOS\/Windows\/Linux \u2014 pipx<\/h3>\n\n\n
                  pipx uninstall pre-commit<\/code><\/span><\/pre>\n\n\n
                  Ubuntu\/Debian \u2014 APT<\/h3>\n\n\n
                  sudo apt remove pre-commit<\/code><\/span><\/pre>\n\n\n
                  Project Virtual Environment<\/h3>\n\n\n\n
                  If pre-commit is installed in an activated virtual environment:<\/p>\n\n\n
                  python -m pip uninstall pre-commit<\/code><\/span><\/pre>\n\n\n
                  Removing the application does not automatically remove every repository configuration file.<\/p>\n\n\n\n
                  If you no longer want the project configuration, remove .pre-commit-config.yaml<\/code> separately and update the repository as appropriate.<\/p>\n\n\n\n
                  \n\n\n\n
                  20. pre-commit Installation Command Cheat Sheet<\/h1>\n\n\n\n
                  Operating system<\/th>Recommended installation<\/th><\/tr>
                  macOS Intel<\/td>brew install pre-commit<\/code><\/td><\/tr>
                  macOS Apple Silicon<\/td>brew install pre-commit<\/code><\/td><\/tr>
                  Windows 10\/11<\/td>pipx install pre-commit<\/code><\/td><\/tr>
                  Ubuntu<\/td>pipx install pre-commit<\/code><\/td><\/tr>
                  Debian<\/td>pipx install pre-commit<\/code><\/td><\/tr>
                  Fedora<\/td>pipx install pre-commit<\/code><\/td><\/tr>
                  RHEL\/CentOS<\/td>Install using pipx or an isolated Python virtual environment<\/td><\/tr>
                  macOS\/Linux with pipx<\/td>pipx install pre-commit<\/code><\/td><\/tr>
                  Python virtual environment<\/td>python -m pip install pre-commit<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                  Essential Configuration Commands<\/h3>\n\n\n
                  # Check version<\/span>\npre-commit --version\n\n# Generate sample configuration<\/span>\npre-commit sample-config\n\n# Validate configuration<\/span>\npre-commit validate-config\n\n# Install Git hook<\/span>\npre-commit install\n\n# Install hook environments<\/span>\npre-commit install-hooks\n\n# Run against all tracked files<\/span>\npre-commit run --all-files\n\n# Run on staged files<\/span>\npre-commit run\n\n# Update hook versions<\/span>\npre-commit autoupdate\n\n# Clear cached environments<\/span>\npre-commit clean\n\n# Remove installed Git hook<\/span>\npre-commit uninstall<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                  \n\n\n\n
                  21. Frequently Asked Questions<\/h1>\n\n\n\n
                  Q1. Is pre-commit free and open source?<\/h3>\n\n\n\n
                  Yes. pre-commit is an open-source framework distributed under the MIT license.<\/p>\n\n\n\n
                  Q2. Is pre-commit only for Python projects?<\/h3>\n\n\n\n
                  No. Although pre-commit is implemented in Python, it supports hooks for many languages and tools, including JavaScript, Python, Go, Ruby, and others.<\/p>\n\n\n\n
                  Q3. Does pre-commit support Terraform?<\/h3>\n\n\n\n
                  Yes. Community hook collections provide Terraform formatting, validation, and other Infrastructure-as-Code checks.<\/p>\n\n\n\n
                  Q4. Does pre-commit work on Windows?<\/h3>\n\n\n\n
                  Yes. pre-commit supports Windows and can be installed through Python tooling such as pipx.<\/p>\n\n\n\n
                  Some individual hooks may require WSL or other platform-specific dependencies, so check the requirements of each hook.<\/p>\n\n\n\n
                  Q5. Is pre-commit automatically enabled after installation?<\/h3>\n\n\n\n
                  No.<\/p>\n\n\n\n
                  Installing the executable makes the command available, but you must configure it in your repository and run:<\/p>\n\n\n
                  pre-commit install<\/code><\/span><\/pre>\n\n\n
                  Q6. Does pre-commit run automatically when I commit?<\/h3>\n\n\n\n
                  Yes, after the appropriate Git hook launcher is installed in that repository.<\/p>\n\n\n\n
                  Q7. Does pre-commit check every file during each commit?<\/h3>\n\n\n\n
                  Normally, pre-commit-stage hooks operate on applicable staged files.<\/p>\n\n\n\n
                  To check all applicable tracked files:<\/p>\n\n\n
                  pre-commit run --all-files<\/code><\/span><\/pre>\n\n\n
                  Q8. Can pre-commit automatically fix code?<\/h3>\n\n\n\n
                  Yes. Many hooks can modify files to correct formatting or other supported issues.<\/p>\n\n\n\n
                  Not every hook supports automatic fixes.<\/p>\n\n\n\n
                  Q9. Can pre-commit detect secrets?<\/h3>\n\n\n\n
                  It can run hooks that detect certain secrets or private-key patterns.<\/p>\n\n\n\n
                  For broader protection, integrate a dedicated secret scanner and server-side secret detection.<\/p>\n\n\n\n
                  Q10. Should pre-commit run in CI\/CD?<\/h3>\n\n\n\n
                  Yes. Running the same checks in CI\/CD reduces the risk of bypassed or missing local hooks.<\/p>\n\n\n\n
                  Q11. Can I run pre-commit without installing Git hooks?<\/h3>\n\n\n\n
                  Yes. With a configuration present, you can run:<\/p>\n\n\n
                  pre-commit run --all-files<\/code><\/span><\/pre>\n\n\n
                  The Git launcher is required for automatic execution during commits, not for manual execution.<\/p>\n\n\n\n
                  Q12. Does pre-commit replace code review?<\/h3>\n\n\n\n
                  No. It helps automate repetitive checks but does not replace human review of correctness, architecture, security, or maintainability.<\/p>\n\n\n\n
                  \n\n\n\n
                  22. Best Practices for Teams and Production Projects<\/h1>\n\n\n\n
                  For reliable adoption across development teams, follow these recommendations:<\/p>\n\n\n\n
                    \n
                  1. Keep .pre-commit-config.yaml<\/code> under version control.<\/li>\n\n\n\n
                  2. Pin hook repositories to reviewed versions or commit references.<\/li>\n\n\n\n
                  3. Use the same configuration locally and in CI\/CD.<\/li>\n\n\n\n
                  4. Select fast hooks for the pre-commit stage.<\/li>\n\n\n\n
                  5. Run expensive tests and scans in CI\/CD or pre-push stages when appropriate.<\/li>\n\n\n\n
                  6. Use pre-commit run --all-files<\/code> when introducing new hooks to an existing repository.<\/li>\n\n\n\n
                  7. Review automatic formatting changes before committing.<\/li>\n\n\n\n
                  8. Avoid excluding large portions of the codebase without a clear reason.<\/li>\n\n\n\n
                  9. Do not rely on local hooks alone for security enforcement.<\/li>\n\n\n\n
                  10. Use standard, maintained hook collections rather than unnecessary custom scripts.<\/li>\n\n\n\n
                  11. Review third-party hooks before executing them because hooks can run code on developer machines and CI runners.<\/li>\n\n\n\n
                  12. Update hook versions through a controlled review process.<\/li>\n\n\n\n
                  13. Document any platform-specific requirements for contributors.<\/li>\n\n\n\n
                  14. Include pre-commit setup instructions in the project README or onboarding documentation.<\/li>\n\n\n\n
                  15. Keep hook execution fast enough that developers do not routinely bypass it.<\/li>\n<\/ol>\n\n\n\n
                    \n\n\n\n
                    23. Conclusion<\/h1>\n\n\n\n
                    pre-commit is a practical tool for improving code consistency, reducing avoidable mistakes, and bringing automated quality checks earlier into the development workflow.<\/p>\n\n\n\n
                    It works across macOS, Windows, and Linux and can be used with virtually any Git-based software project.<\/p>\n\n\n\n
                    For most users, installation is straightforward:<\/p>\n\n\n\n
                    macOS:<\/strong><\/p>\n\n\n
                    brew install pre-commit<\/code><\/span><\/pre>\n\n\n
                    Windows:<\/strong><\/p>\n\n\n
                    pipx install pre-commit<\/code><\/span><\/pre>\n\n\n
                    Linux:<\/strong><\/p>\n\n\n
                    pipx install pre-commit<\/code><\/span><\/pre>\n\n\n
                    Once installed, the essential setup process is:<\/p>\n\n\n
                    # Create or configure .pre-commit-config.yaml<\/span>\n\n# Validate configuration<\/span>\npre-commit validate-config\n\n# Install the Git hook<\/span>\npre-commit install\n\n# Prepare hook environments<\/span>\npre-commit install-hooks\n\n# Run against all tracked files<\/span>\npre-commit run --all-files<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                    From that point onward, supported hooks automatically execute when the corresponding Git events occur.<\/p>\n\n\n\n
                    By combining local pre-commit hooks with CI\/CD checks, development teams can catch common issues earlier, maintain consistent coding standards, and spend more time reviewing meaningful code changes rather than repetitive formatting problems.<\/p>\n\n\n\n
                    \n\n\n\n
                    Official Documentation and References<\/h2>\n\n\n\n