feat: add generic pre/post command hooks (#50)

* feat: add generic pre/post command hooks

Add configurable hooks that run before/after wt operations (create,
checkout, remove, pr, mr). Pre-hooks abort on failure; post-hooks
warn only. Hooks receive environment variables (WT_PATH, WT_BRANCH,
WT_MAIN, WT_REPO_NAME, WT_REPO_HOST, WT_REPO_OWNER) and can be
disabled via WT_HOOKS_DISABLED=1.

- Add Hooks struct and [hooks] config section in config.toml
- Implement runHooks(), getHooks(), buildHookEnv() helpers
- Wire pre/post hooks into create, checkout, pr, mr, remove commands
- Update 'wt info' to display configured hooks
- Add unit tests and E2E scenarios

* feat: add .env copy example with conditional hook pattern

Update default config template to use safe conditional pattern:
  test -f $WT_MAIN/.env && cp $WT_MAIN/.env $WT_PATH/.env || true

Add E2E tests verifying .env is copied when present in main
checkout, and silently skipped when absent.

* docs: add hooks section to README

* docs: only show .env copy on post_create, not post_checkout

The .env copy is a one-time setup step — it belongs on post_create only.
Using it on post_checkout would overwrite locally modified .env files
when a worktree is re-created for the same branch.

* fix: explicitly discard post-hook return values to satisfy errcheck

Author: timvw

README.md

@@ -17,6 +17,7 @@ Inspired by [haacked/dotfiles/tree-me](https://github.com/haacked/dotfiles/blob/
 - **Interactive selection menus** for checkout, remove, pr, and mr commands
 - GitHub PR support via `wt pr` command (uses `gh` CLI) — checks out the PR's actual branch name
 - GitLab MR support via `wt mr` command (uses `glab` CLI) — checks out the MR's actual branch name
+- **Pre/post command hooks** — run custom scripts (e.g. copy `.env`, install deps) on create/checkout/remove
 - Shell integration with auto-cd functionality
 - Tab completion for Bash and Zsh
 
@@ -363,6 +364,62 @@ pattern = "{.repo.Main}/../{.repo.Name}/{.branch}"
 
 Run `wt info` to see the active strategy, pattern, and available variables.
 
+### Hooks
+
+Hooks let you run custom commands before or after `wt` operations. Define them in the `[hooks]` section of your config file:
+
+```toml
+# ~/.config/wt/config.toml
+[hooks]
+post_create = ["test -f $WT_MAIN/.env && cp $WT_MAIN/.env $WT_PATH/.env || true"]
+post_checkout = ["cd $WT_PATH && npm install"]
+pre_remove = ["echo Removing worktree at $WT_PATH"]
+```
+
+**Available hooks:**
+
+| Hook | When it runs |
+| --- | --- |
+| `pre_create` / `post_create` | Before/after `wt create` |
+| `pre_checkout` / `post_checkout` | Before/after `wt checkout` (alias `wt co`) |
+| `pre_remove` / `post_remove` | Before/after `wt remove` (alias `wt rm`) |
+| `pre_pr` / `post_pr` | Before/after `wt pr` |
+| `pre_mr` / `post_mr` | Before/after `wt mr` |
+
+Hooks only run when a **new worktree is actually created** (or removed). If a worktree already exists, the early-return path skips hooks entirely.
+
+**Environment variables** available in hook commands:
+
+| Variable | Description |
+| --- | --- |
+| `$WT_PATH` | Worktree path being created/removed |
+| `$WT_BRANCH` | Branch name |
+| `$WT_MAIN` | Path to the main worktree |
+| `$WT_REPO_NAME` | Repository name |
+| `$WT_REPO_HOST` | Git host (e.g. `github.com`) |
+| `$WT_REPO_OWNER` | Repository owner/group |
+
+**Behavior:**
+
+- **Pre-hooks** abort the operation if any command exits non-zero
+- **Post-hooks** print a warning on failure but do not fail the `wt` command
+- Each hook is a list of shell commands executed via `sh -c` (or `cmd /c` on Windows)
+- Set `WT_HOOKS_DISABLED=1` to skip all hooks (useful for scripting or CI)
+
+**Common patterns:**
+
+```toml
+[hooks]
+# Copy .env file to new worktrees (only if it exists in main)
+post_create = ["test -f $WT_MAIN/.env && cp $WT_MAIN/.env $WT_PATH/.env || true"]
+
+# Install dependencies after checkout
+post_checkout = ["cd $WT_PATH && npm install"]
+
+# Run cleanup before removing a worktree
+pre_remove = ["cd $WT_PATH && npm run clean"]
+```
+
 ### Example: Task spanning multiple repositories
 
 When a task or story requires changes across multiple repositories (e.g. a shared library and a main application), you can organize worktrees by feature instead of by repo using a custom pattern:

config.go

@@ -16,6 +16,21 @@ type Config struct {
 	Strategy  string `toml:"strategy"`
 	Pattern   string `toml:"pattern"`
 	Separator string `toml:"separator"`
+	Hooks     Hooks  `toml:"hooks"`
+}
+
+// Hooks holds pre/post command hook commands.
+type Hooks struct {
+	PreCreate    []string `toml:"pre_create"`
+	PostCreate   []string `toml:"post_create"`
+	PreCheckout  []string `toml:"pre_checkout"`
+	PostCheckout []string `toml:"post_checkout"`
+	PreRemove    []string `toml:"pre_remove"`
+	PostRemove   []string `toml:"post_remove"`
+	PrePR        []string `toml:"pre_pr"`
+	PostPR       []string `toml:"post_pr"`
+	PreMR        []string `toml:"pre_mr"`
+	PostMR       []string `toml:"post_mr"`
 }
 
 // configSource tracks where each config value came from.
@@ -35,6 +50,9 @@ var configFileFound bool
 // configSources tracks the origin of each resolved value.
 var configSources configSource
 
+// worktreeHooks holds the loaded hook configuration.
+var worktreeHooks Hooks
+
 // configFlag is the --config flag value (set by cobra).
 var configFlag string
 
@@ -65,6 +83,17 @@ const defaultConfigTemplate = `# wt configuration file
 # Example: group worktrees by a FEATURE environment variable
 # strategy = "custom"
 # pattern = "{.worktreeRoot}/{.env.FEATURE}/{.repo.Name}"
+
+# Hooks — run commands before/after wt operations
+# Available env vars in hooks: $WT_PATH, $WT_BRANCH, $WT_MAIN,
+#                              $WT_REPO_NAME, $WT_REPO_HOST, $WT_REPO_OWNER
+# Pre-hooks abort on failure; post-hooks warn only.
+# Set WT_HOOKS_DISABLED=1 to skip all hooks.
+#
+# [hooks]
+# post_create = ["test -f $WT_MAIN/.env && cp $WT_MAIN/.env $WT_PATH/.env || true"]
+# post_checkout = ["cd $WT_PATH && npm install"]
+# pre_remove = ["echo Removing $WT_PATH"]
 `
 
 // configDir returns the directory where wt config files are stored.
@@ -112,6 +141,9 @@ func loadWorktreeConfig() {
 		Separator: "default",
 	}
 
+	// Reset hooks
+	worktreeHooks = Hooks{}
+
 	// 2. Load config file
 	configFilePath = resolveConfigPath(configFlag)
 	configFileFound = false
@@ -136,6 +168,7 @@ func loadWorktreeConfig() {
 				worktreeSeparator = cfg.Separator
 				configSources.Separator = "config file"
 			}
+			worktreeHooks = cfg.Hooks
 		}
 	}
 

e2e/scenarios/hooks.yaml

@@ -0,0 +1,98 @@
+# E2E tests for pre/post command hooks
+name: hooks
+description: Test pre/post command hook functionality
+
+scenarios:
+  - name: post_create_hook_runs
+    description: Post-create hook executes after worktree creation
+    skip_os: [windows]
+    skip_shellenv: true
+    steps:
+      # Write a config file with a post_create hook, then create worktree
+      - run: mkdir -p "$TEST_DIR/config" && printf '[hooks]\npost_create = ["touch $WT_PATH/.hook-ran"]\n' > "$TEST_DIR/config/config.toml" && WT_CONFIG="$TEST_DIR/config/config.toml" $WT_BIN create hook-test
+        expect:
+          exit_code: 0
+      - run: test -f "$WORKTREE_ROOT/test-repo/hook-test/.hook-ran" && echo "HOOK_RAN" || echo "HOOK_MISSING"
+        expect:
+          output_contains: "HOOK_RAN"
+
+  - name: pre_create_hook_aborts
+    description: Pre-create hook failure prevents worktree creation
+    skip_shellenv: true
+    skip_os: [windows]
+    steps:
+      - run: mkdir -p "$TEST_DIR/config" && printf '[hooks]\npre_create = ["false"]\n' > "$TEST_DIR/config/config.toml" && WT_CONFIG="$TEST_DIR/config/config.toml" $WT_BIN create blocked-branch
+        expect:
+          exit_code: 1
+      - run: $WT_BIN list
+        expect:
+          output_not_contains: "blocked-branch"
+
+  - name: hooks_disabled_env
+    description: WT_HOOKS_DISABLED=1 skips all hooks
+    skip_os: [windows]
+    skip_shellenv: true
+    steps:
+      - run: mkdir -p "$TEST_DIR/config" && printf '[hooks]\npre_create = ["false"]\n' > "$TEST_DIR/config/config.toml" && WT_CONFIG="$TEST_DIR/config/config.toml" WT_HOOKS_DISABLED=1 $WT_BIN create should-succeed
+        expect:
+          exit_code: 0
+
+  - name: post_checkout_hook_runs
+    description: Post-checkout hook executes after worktree checkout
+    skip_os: [windows]
+    skip_shellenv: true
+    setup:
+      - create_branch: hook-co-branch
+    steps:
+      - run: mkdir -p "$TEST_DIR/config" && printf '[hooks]\npost_checkout = ["touch $WT_PATH/.checkout-hook-ran"]\n' > "$TEST_DIR/config/config.toml" && WT_CONFIG="$TEST_DIR/config/config.toml" $WT_BIN checkout hook-co-branch
+        expect:
+          exit_code: 0
+      - run: test -f "$WORKTREE_ROOT/test-repo/hook-co-branch/.checkout-hook-ran" && echo "HOOK_RAN" || echo "HOOK_MISSING"
+        expect:
+          output_contains: "HOOK_RAN"
+
+  - name: pre_remove_hook_runs
+    description: Pre-remove hook executes before worktree removal
+    skip_os: [windows]
+    skip_shellenv: true
+    setup:
+      - create_branch: rm-hook-branch
+    steps:
+      - run: $WT_BIN checkout rm-hook-branch
+        expect:
+          exit_code: 0
+      - cd: $REPO_DIR
+      - run: mkdir -p "$TEST_DIR/config" && printf '[hooks]\npre_remove = ["echo HOOK_PRE_REMOVE"]\n' > "$TEST_DIR/config/config.toml" && WT_CONFIG="$TEST_DIR/config/config.toml" $WT_BIN remove rm-hook-branch
+        expect:
+          exit_code: 0
+          output_contains: "HOOK_PRE_REMOVE"
+
+  - name: copy_env_file_when_exists
+    description: Post-create hook copies .env from main to worktree when it exists
+    skip_os: [windows]
+    skip_shellenv: true
+    setup:
+      - create_file:
+          path: .env
+          content: "SECRET_KEY=abc123"
+      - git_add: .env
+      - git_commit: "add .env file"
+    steps:
+      - run: mkdir -p "$TEST_DIR/config" && printf '[hooks]\npost_create = ["test -f $WT_MAIN/.env && cp $WT_MAIN/.env $WT_PATH/.env || true"]\n' > "$TEST_DIR/config/config.toml" && WT_CONFIG="$TEST_DIR/config/config.toml" $WT_BIN create env-branch
+        expect:
+          exit_code: 0
+      - run: cat "$WORKTREE_ROOT/test-repo/env-branch/.env"
+        expect:
+          output_contains: "SECRET_KEY=abc123"
+
+  - name: copy_env_file_skipped_when_missing
+    description: Post-create hook silently skips when .env does not exist in main
+    skip_os: [windows]
+    skip_shellenv: true
+    steps:
+      - run: mkdir -p "$TEST_DIR/config" && printf '[hooks]\npost_create = ["test -f $WT_MAIN/.env && cp $WT_MAIN/.env $WT_PATH/.env || true"]\n' > "$TEST_DIR/config/config.toml" && WT_CONFIG="$TEST_DIR/config/config.toml" $WT_BIN create no-env-branch
+        expect:
+          exit_code: 0
+      - run: test -f "$WORKTREE_ROOT/test-repo/no-env-branch/.env" && echo "ENV_EXISTS" || echo "ENV_MISSING"
+        expect:
+          output_contains: "ENV_MISSING"