Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Hook commands for `wt hook` subcommand.
//!
//! This module contains:
//! - `run_hook` - Execute a specific hook type
//! - `handle_hook_show` - Display configured hooks
use std::fmt::Write as _;
use anyhow::Context;
use color_print::cformat;
use strum::IntoEnumIterator;
use worktrunk::HookType;
use worktrunk::config::{
ALIAS_ARGS_KEY, Approvals, CommandConfig, ProjectConfig, ProjectId, UserConfig, binds_cli_var,
referenced_vars_for_config,
};
use worktrunk::git::Repository;
use worktrunk::path::format_path_for_display;
use worktrunk::styling::{
INFO_SYMBOL, PROMPT_SYMBOL, eprintln, format_bash_with_gutter, format_heading, info_message,
println, warning_message,
};
use crate::output::print_json;
use super::command_approval::approve_hooks_filtered;
use super::command_executor::{
CommandContext, FailureStrategy, PreparedStep, prepare_steps, render_template_preview,
};
use super::context::CommandEnv;
use super::hook_filter::selected_hook_configs;
use super::hooks::{HookAnnouncer, prepare_and_check, run_hooks_foreground};
use super::project_config::command_label;
use super::template_vars::TemplateVars;
use worktrunk::config::HookSource;
fn run_post_hook(
ctx: &CommandContext,
foreground: Option<bool>,
user_config: Option<&CommandConfig>,
project_config: Option<&CommandConfig>,
hook_type: HookType,
extra_vars: &[(&str, &str)],
name_filters: &[String],
) -> anyhow::Result<()> {
// --foreground is for debugging; default is background.
if foreground.unwrap_or(false) {
return run_hooks_foreground(
ctx,
user_config,
project_config,
hook_type,
extra_vars,
name_filters,
FailureStrategy::Warn,
)
.map(drop);
}
// Each source runs independently, including when names are filtered.
let mut announcer = HookAnnouncer::new(ctx.repo, false);
let steps = prepare_and_check(
ctx,
user_config,
project_config,
hook_type,
extra_vars,
name_filters,
)?;
announcer.add_steps(ctx, hook_type, None, steps);
announcer.flush()
}
/// Build best-effort directional vars for manual `wt hook` invocation.
///
/// When hooks run during real operations (switch, merge, remove), each call site
/// builds precise vars from the actual source/destination context. When invoked
/// manually via `wt hook <type>`, we only have the current worktree — so each
/// hook type gets the directional vars its real call site sets, filled in from
/// that worktree. The merge and remove hooks bind `target` and
/// `target_worktree_path` to it; the switch and start hooks also bind `base`
/// and `base_worktree_path`, naming the source a real switch starts from,
/// which manually is that same worktree; the commit hooks bind `target` to the
/// default branch as a stand-in for the target their real callers pass — the
/// merge target from `wt merge`, the integration target from `wt step squash`
/// — since `wt step commit` itself passes none.
///
/// The directional *path* vars apply either way, since the worktree exists
/// whether or not it is on a branch. The directional *branch* vars follow
/// `branch` itself: a detached worktree leaves them unset rather than naming
/// the literal `HEAD` (issue #4009).
///
/// This is the single source of truth for manual hook context — both `run_hook`
/// (execution + dry-run) and [`hook_command_rows`] (`hook show --expanded`) use
/// this function. Returns a `TemplateVars` so callers can extend with
/// additional bindings (e.g. CLI shorthand) before materializing.
fn build_manual_hook_template_vars(ctx: &CommandContext, hook_type: HookType) -> TemplateVars {
let branch = ctx.branch;
let worktree_path = ctx.worktree_path;
match hook_type {
// Merge/commit hooks: target = merge target (default branch for commit,
// current for merge). Only this arm needs the default branch, and
// resolving it can cost a `git ls-remote` on a fresh clone — so it is
// fetched here rather than up front.
HookType::PreCommit | HookType::PostCommit => ctx
.repo
.default_branch()
.map_or_else(TemplateVars::new, |t| TemplateVars::new().with_target(&t)),
HookType::PreMerge | HookType::PostMerge => TemplateVars::new()
.with_target_opt(branch)
.with_target_worktree_path(worktree_path),
// Switch hooks: base = current (we're "switching from" here)
HookType::PreSwitch | HookType::PreCreate | HookType::PostCreate | HookType::PostSwitch => {
TemplateVars::new()
.with_base(branch, worktree_path)
.with_target_opt(branch)
.with_target_worktree_path(worktree_path)
}
// Remove hooks: target = where user ends up (current worktree is the best guess)
HookType::PreRemove | HookType::PostRemove => TemplateVars::new()
.with_target_opt(branch)
.with_target_worktree_path(worktree_path),
}
}
/// Parse a raw `KEY=VALUE` shorthand token into a canonicalized
/// `(canonical_key, original_key, value)` triple.
///
/// Canonicalization replaces `-` with `_` in the key to match the template
/// naming convention (minijinja parses `{{ my-var }}` as subtraction), the
/// same rule `parse_key_val` applies to `--var`. The original key is preserved
/// for reconstructing `--KEY=VALUE` when forwarding to `{{ args }}`.
fn parse_shorthand_token(raw: &str) -> anyhow::Result<(String, String, String)> {
let (key, value) = raw
.split_once('=')
.ok_or_else(|| anyhow::anyhow!("invalid shorthand (missing `=`): {raw}"))?;
if key.is_empty() {
anyhow::bail!("invalid shorthand (empty key): {raw}");
}
Ok((key.replace('-', "_"), key.to_string(), value.to_string()))
}
/// Union of top-level variables referenced by selected commands.
/// A reference in any selected step makes the variable a binding candidate.
fn referenced_vars_union(
selected: &[(HookSource, CommandConfig)],
hook_type: HookType,
) -> anyhow::Result<std::collections::BTreeSet<String>> {
let mut out = std::collections::BTreeSet::new();
for (source, config) in selected {
out.extend(referenced_vars_for_config(config, |name| {
source.hook_label(hook_type, name)
})?);
}
Ok(out)
}
/// CLI-origin arguments to a manual `wt hook <type>` invocation. Bundled so
/// the call sites in `main.rs` don't balloon past clippy's
/// `too_many_arguments` threshold as the shorthand/forwarding surface grows.
pub struct HookCliArgs<'a> {
/// Positional name filters: `wt hook pre-merge test build` → `["test", "build"]`.
pub name_filters: &'a [String],
/// Explicit `--var KEY=VALUE` bindings (deprecated force-bind).
pub explicit_vars: &'a [(String, String)],
/// Raw `KEY=VALUE` tokens from the `--KEY=VALUE` shorthand. Smart-routed:
/// bind if a selected template references KEY, else forward to `{{ args }}`.
pub shorthand_vars: &'a [String],
/// Tokens after `--` that forward to `{{ args }}` verbatim.
pub forwarded_args: &'a [String],
}
/// Handle `wt hook` command
///
/// Runs configured user and project hooks selected by optional source/name filters.
///
/// Works in detached HEAD state - the `{{ branch }}` template variable (and the
/// `{{ base }}` / `{{ target }}` names derived from it) is simply unset there.
///
/// Template variables come from three sources in [`HookCliArgs`], routed per
/// alias semantics:
/// - `shorthand_vars` (`--KEY=VALUE`): binds `{{ KEY }}` if a selected hook template
/// references it; otherwise forwards `--KEY=VALUE` into `{{ args }}`.
/// - `forwarded_args` (tokens after `--`): forwards into `{{ args }}` verbatim.
/// - `explicit_vars` (`--var KEY=VALUE`): deprecated force-bind. Always binds,
/// regardless of whether any template references the key.
///
/// The `foreground` parameter controls execution mode for hooks that normally run
/// in background (post-start, post-switch):
/// - `None` = use default behavior for this hook type
/// - `Some(true)` = run in foreground (for debugging)
/// - `Some(false)` = run in background (default for post-start/post-switch)
pub fn run_hook(
hook_type: HookType,
yes: bool,
foreground: Option<bool>,
dry_run: bool,
cli: HookCliArgs<'_>,
) -> anyhow::Result<()> {
let HookCliArgs {
name_filters,
explicit_vars,
shorthand_vars,
forwarded_args,
} = cli;
// `config` isn't in hand here, so let the repository supply its cached load.
let config = Repository::current()?.user_config().clone();
let env = CommandEnv::for_selector(config, "@")?;
let repo = &env.repo;
let ctx = env.context(yes);
// Load project config (optional - user hooks can run without project config)
let project_config = repo.load_project_config()?;
if !dry_run {
// "Approve at the Gate": approve project hooks upfront
// Pass name_filters to only approve the targeted hooks, not all hooks of this type
let approved = approve_hooks_filtered(&ctx, &[hook_type], name_filters)?;
// If declined, return early - the whole point of `wt hook` is to run hooks
if !approved {
eprintln!("{}", worktrunk::styling::info_message("Commands declined"));
return Ok(());
}
}
// Get effective user hooks (global + per-project merged)
let user_hooks = ctx.config.hooks(ctx.project_id().as_ref());
let user_config = user_hooks.get(hook_type);
let proj_config = project_config.as_ref().and_then(|c| c.hooks.get(hook_type));
// No hooks configured: warn and exit successfully. Running hooks that
// don't exist is a no-op, so scripts can invoke `wt hook <type>`
// unconditionally without special-casing empty configuration.
if user_config.is_none() && proj_config.is_none() {
eprintln!(
"{}",
warning_message(format!("No {hook_type} hooks configured"))
);
return Ok(());
}
// Smart-route shorthand: bind when the template references the key,
// forward otherwise. Mirrors `AliasOptions::parse` for the alias path.
let selected = selected_hook_configs(user_config, proj_config, name_filters);
let referenced = referenced_vars_union(&selected, hook_type)?;
let mut bindings: Vec<(String, String)> = Vec::new();
let mut args: Vec<String> = Vec::new();
for raw in shorthand_vars {
let (canon_key, orig_key, value) = parse_shorthand_token(raw)?;
if binds_cli_var(&canon_key, &referenced) {
bindings.push((canon_key, value));
} else {
args.push(format!("--{orig_key}={value}"));
}
}
args.extend(forwarded_args.iter().cloned());
// Explicit `--var KEY=VALUE` is deprecated — prefer `--KEY=VALUE`. It
// still force-binds (useful when a template references the key only
// conditionally, e.g. `{% if override %}`), so keep the binding.
if !explicit_vars.is_empty() {
eprintln!(
"{}",
warning_message(
"--var is deprecated; use --KEY=VALUE shorthand (binds automatically when a selected hook template references KEY)",
)
);
bindings.extend(explicit_vars.iter().cloned());
}
let custom_vars_refs: Vec<(&str, &str)> = bindings
.iter()
.map(|(k, v)| (k.as_str(), v.as_str()))
.collect();
// Build extra vars per hook type (shared by dry-run and execution paths)
// Splice `args` into the template context as a JSON-encoded sequence.
// `expand_template` rehydrates it as `ShellArgs` so bare `{{ args }}`
// renders space-joined with per-element shell escaping. Mirrors
// `run_alias` at `src/commands/alias.rs`.
let args_json =
serde_json::to_string(&args).expect("Vec<String> serialization should never fail");
let template_vars = build_manual_hook_template_vars(&ctx, hook_type);
let mut extra_vars = template_vars.as_extra_vars();
extra_vars.extend(custom_vars_refs.iter().copied());
// Forward positional CLI args as `{{ args }}` (empty sequence when
// nothing was forwarded). `expand_template` rehydrates this JSON into a
// `ShellArgs` sequence that renders space-joined, per-element escaped.
extra_vars.push((ALIAS_ARGS_KEY, &args_json));
if dry_run {
let steps = prepare_and_check(
&ctx,
user_config,
proj_config,
hook_type,
&extra_vars,
name_filters,
)?;
for sourced in steps {
for cmd in sourced.step.into_commands() {
let preview =
render_template_preview(&cmd.template, &cmd.context, repo, &cmd.template_name)?;
let label = if cmd.name.is_some() {
cformat!("{hook_type} <bold>{}</> would run:", cmd.label)
} else {
cformat!("{hook_type} <bold>{}</> hook would run:", cmd.label)
};
// Dry-run preview is the command's answer (the hook that would
// run), so it goes to stdout — see /writing-user-outputs.
println!(
"{}",
info_message(cformat!("{label}\n{}", format_bash_with_gutter(&preview)))
);
}
}
return Ok(());
}
// pre-* hooks block (fail-fast); post-* hooks default to background.
if hook_type.is_pre() {
run_hooks_foreground(
&ctx,
user_config,
proj_config,
hook_type,
&extra_vars,
name_filters,
FailureStrategy::FailFast,
)
.map(drop)
} else {
run_post_hook(
&ctx,
foreground,
user_config,
proj_config,
hook_type,
&extra_vars,
name_filters,
)
}
}
/// Handle `wt hook show` command - display configured hooks
pub fn handle_hook_show(
hook_type_filter: Option<&str>,
expanded: bool,
format: crate::cli::SwitchFormat,
) -> anyhow::Result<()> {
use crate::help_pager::show_help_in_pager;
let config = Repository::current()
.context("Failed to show hooks")?
.user_config()
.clone();
// Show the hooks `wt hook` would run: the project config of the worktree
// `@` names.
let env = CommandEnv::for_selector(config, "@")?;
let repo = &env.repo;
let config = &env.config;
// Preserve the loader's typed source diagnosis through command context.
let project_config: Option<&ProjectConfig> = repo.project_config()?;
let approvals = Approvals::load().context("Failed to load approvals")?;
let project_id = repo.project_identifier().ok();
// Parse hook type filter if provided. clap's value parser already
// validated the string (canonical name or deprecated `-create` alias);
// `parse_hook_type` maps both to the canonical `HookType`.
let filter: Option<HookType> = hook_type_filter
.map(crate::cli::parse_hook_type)
.transpose()?;
// Context for template expansion, only under --expanded. Detached HEAD is
// fine: `{{ branch }}` is unset there, and `--expanded` renders the
// guarded form the way any other unset variable renders.
let ctx = expanded.then(|| env.context(false));
if format == crate::cli::SwitchFormat::Json {
return emit_hook_show_json(
config,
project_config,
&approvals,
project_id.as_ref(),
filter,
ctx.as_ref(),
);
}
let mut output = String::new();
// Render user hooks
render_user_hooks(
&mut output,
config,
&approvals,
project_id.as_ref(),
filter,
ctx.as_ref(),
)?;
output.push('\n');
// Render project hooks
render_project_hooks(
&mut output,
repo,
project_config,
&approvals,
project_id.as_ref(),
filter,
ctx.as_ref(),
)?;
show_help_in_pager(&output, true)?;
Ok(())
}
/// Emit configured hooks as a JSON array of structured records.
///
/// Each record carries the hook type, source (user or project), optional name,
/// raw template, project approval status, and — when `--expanded` was passed —
/// the rendered command preview. `handle_hook_show` builds `ctx` only under
/// `--expanded`, and each row carries whether it was expanded.
fn emit_hook_show_json(
user_config: &UserConfig,
project_config: Option<&ProjectConfig>,
approvals: &Approvals,
project_id: Option<&ProjectId>,
filter: Option<HookType>,
ctx: Option<&CommandContext>,
) -> anyhow::Result<()> {
let mut entries: Vec<serde_json::Value> = Vec::new();
let mut emit =
|hook_type: HookType, source: HookSource, cfg: &CommandConfig| -> anyhow::Result<()> {
for row in hook_command_rows(cfg, ctx, hook_type, source)? {
let mut obj = serde_json::json!({
"type": hook_type.to_string(),
"source": source.to_string(),
"name": row.name,
"template": row.template,
"needs_approval": needs_approval(source, approvals, project_id, &row.template),
});
if let Some(expanded) = row.expanded {
obj["expanded"] = serde_json::Value::String(expanded);
}
entries.push(obj);
}
Ok(())
};
// User hooks (merge global + per-project so the listing matches what runs)
let user_hooks = user_config.hooks(project_id);
for hook_type in HookType::iter() {
if let Some(f) = filter
&& f != hook_type
{
continue;
}
if let Some(cfg) = user_hooks.get(hook_type) {
emit(hook_type, HookSource::User, cfg)?;
}
}
// Project hooks
if let Some(project) = project_config {
for hook_type in HookType::iter() {
if let Some(f) = filter
&& f != hook_type
{
continue;
}
if let Some(cfg) = project.hooks.get(hook_type) {
emit(hook_type, HookSource::Project, cfg)?;
}
}
}
print_json(&entries)?;
Ok(())
}
/// Render user hooks section
fn render_user_hooks(
out: &mut String,
config: &UserConfig,
approvals: &Approvals,
project_id: Option<&ProjectId>,
filter: Option<HookType>,
ctx: Option<&CommandContext>,
) -> anyhow::Result<()> {
let config_path = worktrunk::config::config_path();
writeln!(
out,
"{}",
format_heading(
"USER HOOKS",
Some(
&config_path
.as_ref()
.map(|p| format!("@ {}", format_path_for_display(p)))
.unwrap_or_else(|| "(not found)".to_string())
)
)
)?;
// Merge global and per-project user hooks so display matches what
// actually runs (the execution path also uses `config.hooks(project_id)`).
let user_hooks = config.hooks(project_id);
let hooks: Vec<_> = HookType::iter()
.filter_map(|ht| user_hooks.get(ht).map(|cfg| (ht, cfg)))
.collect();
render_hook_section(
out,
&hooks,
HookSource::User,
approvals,
project_id,
filter,
ctx,
)
}
/// Render project hooks section
fn render_project_hooks(
out: &mut String,
repo: &Repository,
project_config: Option<&ProjectConfig>,
approvals: &Approvals,
project_id: Option<&ProjectId>,
filter: Option<HookType>,
ctx: Option<&CommandContext>,
) -> anyhow::Result<()> {
let config_path = repo
.project_config_path()?
.context("Cannot determine project config location — no worktree found")?;
writeln!(
out,
"{}",
format_heading(
"PROJECT HOOKS",
Some(&format!("@ {}", format_path_for_display(&config_path)))
)
)?;
let Some(config) = project_config else {
writeln!(out, "{}", info_message("Not found"))?;
return Ok(());
};
// Collect all project hooks
let hooks: Vec<_> = HookType::iter()
.filter_map(|ht| config.hooks.get(ht).map(|cfg| (ht, cfg)))
.collect();
render_hook_section(
out,
&hooks,
HookSource::Project,
approvals,
project_id,
filter,
ctx,
)
}
/// Render a section's body: every hook that survives `filter`, or
/// a neutral "No hooks configured" state when nothing remains.
///
/// The fallback keys off what was printed, not off what the config declared —
/// a hook type carrying an empty command list (`post-switch = []`) has an entry
/// but no commands to show, and a section holding only those is empty.
fn render_hook_section(
out: &mut String,
hooks: &[(HookType, &CommandConfig)],
source: HookSource,
approvals: &Approvals,
project_id: Option<&ProjectId>,
filter: Option<HookType>,
ctx: Option<&CommandContext>,
) -> anyhow::Result<()> {
let mut has_any = false;
for (hook_type, config) in hooks {
if let Some(f) = filter
&& f != *hook_type
{
continue;
}
has_any |=
render_hook_commands(out, *hook_type, config, source, approvals, project_id, ctx)?;
}
if !has_any {
writeln!(out, "{}", info_message("No hooks configured"))?;
}
Ok(())
}
/// Render commands for a single hook type, reporting whether it wrote any.
fn render_hook_commands(
out: &mut String,
hook_type: HookType,
config: &CommandConfig,
source: HookSource,
approvals: &Approvals,
project_id: Option<&ProjectId>,
ctx: Option<&CommandContext>,
) -> anyhow::Result<bool> {
let mut wrote_any = false;
for row in hook_command_rows(config, ctx, hook_type, source)? {
wrote_any = true;
let label = command_label(hook_type, row.name.as_deref());
let needs_approval = needs_approval(source, approvals, project_id, &row.template);
// Use ❯ for needs approval, ○ for approved/user hooks
let (emoji, suffix) = if needs_approval {
(PROMPT_SYMBOL, cformat!(" <dim>(requires approval)</>"))
} else {
(INFO_SYMBOL, String::new())
};
writeln!(out, "{emoji} {label}{suffix}")?;
let shown = row.expanded.as_deref().unwrap_or(&row.template);
writeln!(out, "{}", format_bash_with_gutter(shown))?;
}
Ok(wrote_any)
}
/// Whether a listed command still needs the user's approval to run.
///
/// Only project commands do — user config is the user's own. A repo with no
/// project identifier has nothing to key approvals by, so nothing is approved
/// and nothing is flagged.
fn needs_approval(
source: HookSource,
approvals: &Approvals,
project_id: Option<&ProjectId>,
template: &str,
) -> bool {
match source {
HookSource::User => false,
HookSource::Project => {
project_id.is_some_and(|id| !approvals.is_command_approved(id, template))
}
}
}
/// One command in a `wt hook show` listing.
struct HookCommandRow {
name: Option<String>,
template: String,
/// The command as it would run, under `--expanded`. `None` without it, so
/// the listing prints the raw template and the JSON omits the field —
/// neither has to re-derive which mode it is in.
expanded: Option<String>,
}
/// The rows for one hook config, expanded when `ctx` is present —
/// `handle_hook_show` builds one only under `--expanded`.
///
/// Expansion runs the config through [`prepare_steps`], the same function that
/// builds what actually executes, so every context key the execution path
/// gains reaches this preview with no second edit here. Rendering then goes
/// through [`render_template_preview`], shared with `wt hook <type>
/// --dry-run`, which renders each `{{ vars.<key> }}` as itself while the rest
/// of the template expands — those values resolve from git config when the
/// step runs, possibly written by an earlier step.
///
/// A manual invocation has no source or destination worktree, so the
/// directional vars come from [`build_manual_hook_template_vars`], exactly as
/// `run_hook` builds them. `args` is left unset, and `prepare_steps` defaults it
/// to the empty sequence — a listing has no CLI args to forward, which is what
/// that default encodes.
///
/// A template that cannot expand renders as `# <error>` above its raw text
/// rather than propagating — `wt hook show` lists configuration, so one broken
/// template must not blank the rest of the listing.
fn hook_command_rows(
config: &CommandConfig,
ctx: Option<&CommandContext>,
hook_type: HookType,
source: HookSource,
) -> anyhow::Result<Vec<HookCommandRow>> {
// The emptiness check spares a config with no commands the git
// subprocesses `prepare_steps` spawns to build a context nothing reads.
if let Some(ctx) = ctx
&& config.commands().next().is_some()
{
let template_vars = build_manual_hook_template_vars(ctx, hook_type);
let extra_vars = template_vars.as_extra_vars();
return Ok(prepare_steps(config, ctx, &extra_vars, hook_type, source)?
.into_unvalidated()
.into_iter()
.flat_map(PreparedStep::into_commands)
.map(|cmd| {
let template = cmd.template;
let display =
render_template_preview(&template, &cmd.context, ctx.repo, &cmd.template_name)
.unwrap_or_else(|err| format!("# {err}\n{template}"));
HookCommandRow {
name: cmd.name,
template,
expanded: Some(display),
}
})
.collect());
}
Ok(config
.commands()
.map(|cmd| HookCommandRow {
name: cmd.name.clone(),
template: cmd.template.clone(),
expanded: None,
})
.collect())
}