hooks

Documentation

Overview

Package hooks provides post-operation hook execution with placeholder substitution.

Hooks are shell commands defined in config that run after wt operations like add, pr checkout, prune, or merge. They enable workflow automation such as opening editors, installing dependencies, or sending notifications.

Hook Selection

Hooks can run automatically or manually:

• Automatic: Hooks with "on" config matching the command type run automatically
• Manual: Use --hook=name to run a specific hook, --no-hook to skip all

Example config:

[hooks.vscode]
command = "code {path}"
on = ["add", "pr"]  # auto-run for add and pr commands

[hooks.cleanup]
command = "echo 'Done with {branch}'"
# no "on" - only runs via --hook=cleanup

Placeholder Substitution

Static placeholders available in all hooks:

• {path}: Absolute worktree path
• {branch}: Branch name
• {repo}: Repository name from git origin
• {folder}: Main repo folder name
• {main-repo}: Main repo path
• {trigger}: Command that triggered the hook (add, pr, prune, merge)

Custom variables via --arg key=value:

• {key}: Value from --arg key=value
• {key:-default}: Value with fallback if not provided

Execution Context

Hooks run with the working directory set to:

• Worktree path for add/pr hooks
• Main repo path for prune hooks (worktree is deleted)

Hook failures are logged but don't stop batch operations (RunForEach). Use RunAll when hook failure should stop execution.

Stdin Support

Use --arg key=- to read stdin content into a variable:

echo "my content" | wt hook myhook --arg content=-

Index

• func ParseEnv(envSlice []string) (map[string]string, error)
• func ParseEnvWithStdin(envSlice []string) (map[string]string, error)
• func RunAll(matches []HookMatch, ctx Context) error
• func RunAllNonFatal(matches []HookMatch, ctx Context, workDir string)
• func RunForEach(matches []HookMatch, ctx Context, workDir string)
• func RunSingle(name string, hook *config.Hook, ctx Context) error
• func SubstitutePlaceholders(command string, ctx Context) string
• type CommandType
• type Context
  • func ContextFromRepo(repoPath string, trigger CommandType, env map[string]string) Context
  • func ContextFromWorktree(target *resolve.Target, trigger CommandType, env map[string]string) Context
• type HookMatch
  • func SelectHooks(cfg config.HooksConfig, hookName string, noHook bool, cmdType CommandType) ([]HookMatch, error)

Functions

func ParseEnv

func ParseEnv(envSlice []string) (map[string]string, error)

ParseEnv parses a slice of "key=value" strings into a map. Returns an error if any entry doesn't contain "=".

func ParseEnvWithStdin

func ParseEnvWithStdin(envSlice []string) (map[string]string, error)

ParseEnvWithStdin parses a slice of "key=value" strings into a map. If any value is "-", reads stdin content and assigns it to all such keys. Returns an error if stdin is requested but not piped or empty.

func RunAll

func RunAll(matches []HookMatch, ctx Context) error

RunAll runs all matched hooks with the given context. Prints "No hooks matched" if matches is empty, otherwise runs each hook. Returns on first error.

func RunAllNonFatal

func RunAllNonFatal(matches []HookMatch, ctx Context, workDir string)

RunAllNonFatal runs all matched hooks, logging failures as warnings instead of returning errors. Prints "No hooks matched" if matches is empty.

func RunForEach

func RunForEach(matches []HookMatch, ctx Context, workDir string)

RunForEach runs all matched hooks for a single item (e.g., one worktree in a batch). Logs failures as warnings with branch context. Does NOT print "no hooks matched".

func RunSingle

func RunSingle(name string, hook *config.Hook, ctx Context) error

RunSingle runs a single hook by name with the given context. Used by `wt hook` to execute a specific hook manually.

func SubstitutePlaceholders

func SubstitutePlaceholders(command string, ctx Context) string

SubstitutePlaceholders replaces {placeholder} with values from Context.

Static placeholders: {path}, {branch}, {repo}, {folder}, {main-repo}, {trigger} Env placeholders (from Context.Env via --arg key=value):

• {key} - value from --arg key=value
• {key:-default} - value with default if key not set

Types

type CommandType

type CommandType string

CommandType identifies which command is triggering the hook

const (
	CommandAdd   CommandType = "add"
	CommandPR    CommandType = "pr"
	CommandPrune CommandType = "prune"
	CommandMerge CommandType = "merge"
	CommandCd    CommandType = "cd"
)

type Context

type Context struct {
	Path     string            // absolute worktree path
	Branch   string            // branch name
	Repo     string            // repo name from git origin
	Folder   string            // main repo folder name
	MainRepo string            // main repo path
	Trigger  string            // command that triggered the hook (add, pr, prune, merge)
	Env      map[string]string // custom variables from -e key=value flags
	DryRun   bool              // if true, print command instead of executing
}

Context holds the values for placeholder substitution

func ContextFromRepo

func ContextFromRepo(repoPath string, trigger CommandType, env map[string]string) Context

ContextFromRepo builds a Context for a repository (not worktree-specific).

func ContextFromWorktree

func ContextFromWorktree(target *resolve.Target, trigger CommandType, env map[string]string) Context

ContextFromWorktree builds a Context from a resolved worktree target.

type HookMatch

type HookMatch struct {
	Hook *config.Hook
	Name string
}

HookMatch represents a hook that matched the current command

func SelectHooks

func SelectHooks(cfg config.HooksConfig, hookName string, noHook bool, cmdType CommandType) ([]HookMatch, error)

SelectHooks determines which hooks to run based on config and CLI flags. Returns all matching hooks. If hookName is specified, only that hook runs. Otherwise, all hooks with matching "on" conditions run. Returns nil slice if no hooks should run, error if specified hook doesn't exist.