<p align="center"> <img src="docs/githooks-logo.svg"> <strong>v3</strong> </p>

Githooks

A platform-independent hooks manager written in Go to support shared hook repositories and per-repository Git hooks, checked into the working repository. This implementation is the Go port and successor of the original implementation (see Migration).

[!IMPORTANT]

This Git hook manager does one job and only that: running Git hooks. It will never maintain your tools or support language toolchains and all other sidestories you might have to make your hooks execute. There are solutions to this like Nix ❤️‍🔥 or container managers like podman (or docker -> don't).

To make this work, the installer creates run-wrappers for Githooks that are installed into the .git/hooks folders on request (by default). There's more to the story though. When one of the Githooks run-wrappers executes, Githooks starts up and tries to find matching hooks in the .githooks directory under the project root, and invoke them one-by-one. Also it searches for hooks in configured shared hook repositories.

This Git hook manager supports:

• Running repository checked-in hooks.
• Running shared hooks from other Git repositories (with auto-update). See these containerized example hook repositories.
• Git LFS support.
• No it works on my machine by running hooks over containers and automatic build/pull integration of container images (optional) Hint: better run it over Nix DevShells and not containers.
• Command line interface.
• Fast execution due to compiled executable. (even 2-3x faster from v2.1.1)
• Fast parallel execution over threadpool.
• Ignoring non-shared and shared hooks with patterns.
• Automatic Githooks updates: Fully configurable for your own company by url/branch and deploy settings.
• Bonus: Platform-independent dialog tool for user prompts inside your own hooks.

Table of Content

<!--toc:start-->

• Githooks
  • Table of Content
  • Layout and Options
  • Execution
    • Staged Files
    • Hook Run Configuration
    • Parallel Execution
  • Supported Hooks
  • Git Large File Storage (Git LFS) Support
  • Shared Hook Repositories
    • Global Configuration
    • Local Configuration
    • Example Githooks Repositories
    • Repository Configuration
    • Supported URLS
    • Skip Non-Existing Shared Hooks
  • Layout of Shared Hook Repositories
    • Shared Repository Namespace
  • Ignoring Hooks and Files
  • Trusting Hooks
  • Disabling Githooks
  • Environment Variables
    • Arguments to Shared Hooks
  • Log & Traces
  • Installing or Removing Run-Wrappers
  • Running Hooks in Containers
    • Podman Manager (rootless)
    • Docker Manager
    • Pull and Build Integration
    • Locate Githooks Container Images
  • Running Hooks/Scripts Manually
  • User Prompts
  • Installation
    • Quick (Secure)
    • Package Manager nix
    • Procedure
    • Install Modes
    • Install Mode - Manual
    • Install Mode - Centralized Hooks
    • Install from different URL and Branch
    • Use in CI
      • Nested Containers
    • Gitlab Demo
    • No Installation
    • Non-Interactive Installation
    • Install on the Server
      • Setup for Bare Repositories
    • Global Hooks or No Global Hooks
      • Manual: Use Githooks Selectively
      • Centralized: Use Githooks For All Repositories
    • Updates
      • Automatic Update Checks
      • Update Mechanics
  • Uninstalling
  • YAML Specifications
  • Migration
  • Dialog Tool
    • Build From Source
    • Dependencies
  • Tests and Debugging
    • Debugging in the Dev Container
    • Todos
  • Changelog
    • Version v2.x.x
  • FAQ
  • Acknowledgements
  • Authors
  • Support & Donation
  • License
  <!--toc:end-->

Layout and Options

Take this snippet of a Git repository layout as an example:

/
├── .githooks/
│    ├── commit-msg/          # All commit-msg hooks.
│    │    ├── validate        # Normal hook script.
│    │    └── add-text        # Normal hook script.
│    │
│    ├── pre-commit/          # All pre-commit hooks.
│    │    ├── .ignore.yaml    # Ignores relative to 'pre-commit' folder.
│    │    ├── 01-validate     # Normal hook script.
│    │    ├── 02-lint         # Normal hook script.
│    │    ├── 03-test.yaml    # Hook run configuration.
│    │    ├── docs.md         # Ignored in '.ignore.yaml'.
│    │    └── final/          # Batch folder 'final' which runs all in parallel.
│    │        ├── 01-validate # Normal hook script.
│    │        └── 02-upload   # Normal hook script.
│    │
│    ├── post-merge           # An executable file.
│    │
│    ├── post-checkout/       # All post-checkout hooks.
│    │   ├── .all-parallel    # All hooks in this folder run in parallel.
│    │   └── ...
│    ├── ...
│    ├── .images.yaml         # Container image spec for use in e.g `03-test.yaml`.
│    ├── .ignore.yaml         # Main ignores.
│    ├── .shared.yaml         # Shared hook configuration.
│    ├── .envs.yaml           # Environment variables passed to shared hooks.
│    └── .lfs-required        # LFS is required.
└── ...

All hooks to be executed live under the .githooks top-level folder, that should be checked into the repository. Inside, we can have directories with the name of the hook (like commit-msg and pre-commit above), or a file matching the hook name (like post-merge in the example). The filenames in the directory do not matter, but the ones starting with a . (dotfiles) will be excluded by default. All others are executed in lexical order according to the Go function Walk rules. Subfolders as e.g. final get treated as parallel batch and all hooks inside are by default executed in parallel over the thread pool. See Parallel Execution for details.

You can use the command line helper (a globally configured Git alias alias.hooks), that is git hooks list, to list all hooks and their current state that apply to the current repository. For this repository this looks like the following.

Execution

If a file is executable, it is directly invoked, otherwise it is interpreted with the sh shell. On Windows that mostly means dispatching to the bash.exe from https://gitforwindows.org.

All parameters and standard input are forwarded from Git to the hooks. The standard output and standard error of any hook which Githooks runs is captured together<span id="a1">¹</span> and printed to the standard error stream which might or might not get read by Git itself (e.g. pre-push).

Hooks can also be specified by a run configuration in a corresponding YAML file, see Hook Run Configuration.

Staged Files

Hooks related to commit events (where it makes se