GitHoox (GitHoox v0.5.0)

Git hooks in pure Elixir. Configurable file globs, per-hook options, built-in support for mix format, Credo, ExUnit, and Dialyzer, plus a generic mix <task> hook for everything else.

Quickstart

mix git_hoox.install

Add hooks in .git_hoox.exs:

%{
  hooks: [
    pre_commit: [
      {GitHoox.Hooks.Format, []},
      {GitHoox.Hooks.Credo, []}
    ]
  ]
}

See GitHoox.Hook for writing custom hooks.

Summary

Types

config()

Loaded and validated config.

glob()

Glob pattern matched against repo-relative paths.

hook_entry()

Hook entry in config: {Module, keyword_opts}.

hook_result()

Result of a single hook invocation.

path()

Repo-relative file path.

stage()

Git lifecycle stage. See git help hooks.

Functions

run(stage, args \\ [], stdin \\ nil)

Execute all hooks configured for stage.

Types

config()

@type config() :: %{
  hooks: keyword(),
  parallel: boolean(),
  fail_fast: boolean(),
  skip_env: String.t()
}

Loaded and validated config.

glob()

@type glob() :: String.t()

Glob pattern matched against repo-relative paths.

hook_entry()

@type hook_entry() :: {module(), keyword()}

Hook entry in config: {Module, keyword_opts}.

hook_result()

@type hook_result() :: :ok | {:ok, modified :: [path()]} | {:error, term()}

Result of a single hook invocation.

Return :ok for read-only success. Return {:ok, modified} listing files the hook mutated — the runner re-stages them if stage_fixed: true. Return {:error, reason} to fail the hook (and stage, unless the user disabled fail_fast). Any other shape is a contract violation and will raise inside the runner.

path()

@type path() :: String.t()

Repo-relative file path.

stage()

@type stage() ::
  :pre_commit
  | :prepare_commit_msg
  | :commit_msg
  | :post_commit
  | :pre_rebase
  | :post_checkout
  | :post_merge
  | :pre_push

Git lifecycle stage. See git help hooks.

Functions

run(stage, args \\ [], stdin \\ nil)

@spec run(stage(), [String.t()], String.t() | nil) ::
  :ok | {:error, [{module(), term()}]}

Execute all hooks configured for stage.

args are the positional arguments the git shim received (e.g. the commit message file path for commit_msg). stdin is the raw input passed to the shim, only meaningful for pre_push.