precommit

Documentation

Overview

Package precommit detects and manages pre-commit configuration and environment.

Index

• func ConfigFile(root string) (string, bool)
• func EnsureTool(r CommandRunner) (string, error)
• func HookInstalled(r CommandRunner, root string) bool
• func InstallHook(r CommandRunner, root string) (string, error)
• func ToolVersion(r CommandRunner) (string, bool)
• type CommandRunner
  • func NewExecRunner() CommandRunner
• type Options
• type Result
  • func Check(r CommandRunner, opts Options) (Result, error)

Functions

func ConfigFile

func ConfigFile(root string) (string, bool)

ConfigFile returns the path to the pre-commit config in root, and whether one exists.

func EnsureTool

func EnsureTool(r CommandRunner) (string, error)

EnsureTool makes sure the pre-commit tool is available, installing it when necessary. It tries each available installer in order, falling through on failure. It returns a human-readable description of any action taken (empty if the tool was already present) and an error if installation was impossible or every attempt failed.

func HookInstalled

func HookInstalled(r CommandRunner, root string) bool

HookInstalled reports whether the repository's pre-commit git hook exists and was generated by the pre-commit tool. root is the repository root; r is used to resolve the real hooks path so git worktrees (where .git is a file) work.

func InstallHook

func InstallHook(r CommandRunner, root string) (string, error)

InstallHook runs `pre-commit install` in root to set up the git hook.

func ToolVersion

func ToolVersion(r CommandRunner) (string, bool)

ToolVersion returns the installed pre-commit version (e.g. "3.7.0") and whether the tool is available.

Types

type CommandRunner

type CommandRunner interface {
	// Look reports whether an executable named name exists on PATH.
	Look(name string) bool
	// Run executes name with args. If dir != "", it is the working directory.
	// It returns the combined stdout+stderr output and any execution error.
	Run(dir, name string, args ...string) (string, error)
}

CommandRunner runs external commands. It is abstracted so tests can avoid invoking real pre-commit / python binaries.

func NewExecRunner

func NewExecRunner() CommandRunner

NewExecRunner returns a CommandRunner backed by os/exec.

type Options

type Options struct {
	// Root is the git repository root directory.
	Root string
	// AllowInstall permits mutating the environment (installing the tool and/or
	// the git hook) when something is missing.
	AllowInstall bool
	// Run, when true, executes `pre-commit run --all-files` after the environment
	// is confirmed ready.
	Run bool
}

Options controls a Check run.

type Result

type Result struct {
	ConfigFound   bool     `json:"config_found"`
	ToolInstalled bool     `json:"tool_installed"`
	ToolVersion   string   `json:"tool_version,omitempty"`
	HookInstalled bool     `json:"hook_installed"`
	ActionsTaken  []string `json:"actions_taken"`
	RunResult     string   `json:"run_result,omitempty"` // "passed" | "failed" | ""
	RunOutput     string   `json:"run_output,omitempty"` // pre-commit run output when RunResult == "failed"
	OK            bool     `json:"ok"`
}

Result is the structured outcome of a Check. JSON tags match docs/COMMANDS.md.

OK means "nothing blocks committing": it is true when the repository has no pre-commit config (nothing to check), or when the config is present and the tool, hook, and any requested --run all succeeded. Always read OK together with ConfigFound to distinguish "ready" from "no config, skipped".

func Check

func Check(r CommandRunner, opts Options) (Result, error)

Check runs the detection/remediation pipeline and returns a structured Result. It returns a non-nil error only for hard failures (e.g. an install attempt failed). "Not ready" states are reported via Result.OK == false with no error.