* Add --force flag to wt remove for worktrees with untracked files
The --force flag now also passes --force to git worktree remove,
allowing removal of worktrees containing untracked files like build
artifacts (.vite/, node_modules/, etc).
- Extended existing --force flag semantics (was: skip approval prompts)
- Added -f short form for convenience
- wt merge now always forces worktree removal (build artifacts unneeded post-merge)
Fixes#301🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Separate --force into --yes (prompts) and --force (removal)
The --force flag on wt remove had two meanings: skipping approval prompts
AND forcing worktree removal with untracked files. This was confusing and
potentially dangerous.
Now:
- --yes/-y: Skip approval prompts (all commands with prompts)
- --force/-f: Force worktree removal with untracked files (wt remove only)
This follows CLI conventions (apt, npm, etc.) where --yes skips prompts
and --force overrides safety checks.
Breaking change acceptable per project guidelines (early release mode).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix unit test for NotInteractive error message
Update test to check for --yes instead of --force.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
The --force flag now also passes --force to git worktree remove,
allowing removal of worktrees containing untracked files like build
artifacts (.vite/, node_modules/, etc).
- Extended existing --force flag semantics (was: skip approval prompts)
- Added -f short form for convenience
- wt merge now always forces worktree removal (build artifacts unneeded post-merge)
Fixes#301🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
* Update docs and help text to clarify default branch references
* Replace "main" with "default branch" in docs and help text
Update references throughout documentation and help snapshots to use
"default branch" instead of hardcoded "main" for clarity. Changes include:
- Help text descriptions for list, merge, switch, and remove commands
- Configuration file documentation and examples
- JSON output field descriptions
- Status symbol explanations
- Example commands and shortcuts
Also update environment variable from GIT_EDITOR to GIT_CONFIG_GLOBAL
in test snapshots and add missing RUST_LOG variable.
Convert --help-page output to HTML with ANSI colors preserved,
matching how `wt list` outputs render in the web docs. The doc
sync test now converts command reference blocks from markdown
code fences to Zola's {% terminal() %} shortcode with proper
HTML styling.
- Add with_colors parameter to get_help_reference()
- Use std::println! to preserve ANSI codes (bypass anstream TTY detection)
- Add strip_ansi_codes() helper for pattern matching
- Convert command reference blocks to HTML in readme_sync test
- Fix URL typo in config docs (/hooks/ → /hook/)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
The docs linked to `@/switch.md#argument-resolution` but that anchor
doesn't exist - the section in switch.md is named "Shortcuts".
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Clarify which git ref is used for different status checks:
- default_branch (local main): Used for informational stats like ahead/behind
counts, branch diff, and conflict detection (✗ symbol)
- target (effective target): Used for integration checks that determine if a
branch is safe to delete. May be origin/main when it's strictly ahead,
catching branches merged remotely before pulling.
Status symbol mapping:
- _ (Same commit): Uses ahead==0 && behind==0 from counts (vs default_branch)
- ⊂ (Integrated): All 5 checks use target
- ✗ (Would conflict): Uses default_branch for consistency with other Main symbols
Documentation updated to list all 5 integration conditions (added Ancestor
between Same commit and No added changes) and clarify which compare against
main vs target.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
When resolving a branch argument in `wt switch` and `wt remove`, now
checks if the branch has a worktree anywhere before checking the
expected path. This is more intuitive - if you type `wt switch foo`,
you get branch foo's worktree, not whatever happens to be at the
expected path.
- Rename resolve_worktree_path_first → resolve_worktree_arg
- Reorder handle_switch to check branch first
- Remove unused WorktreePathMismatch error type
- Simplify argument resolution documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Update documentation and help text to better explain the switch command's behavior when creating worktrees. Restructure the "Creating worktrees" section to clarify that worktree creation happens when the target branch has no worktree, separate from the `--create` flag which specifically creates a new branch. Simplify the introductory description and update examples to be more concise and practical.
Update help text for all state subcommands (default-branch, previous-branch,
ci-status, marker, logs) with detailed explanations of detection/behavior,
use cases, and examples. Remove horizontal rule separators between sections
in generated docs. Update help snapshots to reflect expanded output.
* feat: Add user-level hooks that run for all repositories
Implement a new user hooks system that allows developers to define
personal hooks in `~/.config/worktrunk/config.toml` that execute for
all repositories. User hooks complement project hooks with these key
differences:
- **Scope**: Run for all repositories (vs. single repository)
- **Location**: User config file (vs. `.config/wt.toml`)
- **Approval**: Not required (user implicitly approves via config)
- **Execution order**: Run before project hooks
- **Skip behavior**: Skipped together with project hooks via `--no-verify`
### Implementation Details
**Configuration syntax** (same as project hooks):
```toml
[post-create]
setup = "echo 'Setting up worktree...'"
[pre-merge]
notify = "notify-send 'Merging {{ branch }}'"
```
**Hook types supported**: post-create, post-start, pre-commit, pre-merge,
post-merge, pre-remove
**Template variables**: Support all project hook variables plus `remote_url`
for repository-specific conditional logic
**New data structures**:
- `HookSource` enum: Distinguishes user vs. project hooks
- `prepare_user_commands()`: Expands user hook templates without approval
**Updated hook pipeline**:
- `HookPipeline::run_sequential()`: Accepts `HookSource` instead of
`phase` and `label_prefix`
- `HookPipeline::spawn_background()`: Renamed from `spawn_detached()` for
consistency
### Documentation Updates
- Updated help text and documentation to clarify `--no-verify` skips all
hooks (both user and project)
- Added "User hooks" section to config documentation with examples
- Added comparison table showing key differences from project hooks
- Added use cases and filtering examples
### Tests
Added comprehensive integration test suite (`tests/integration_tests/user_hooks.rs`)
covering:
- Basic execution of all hook types
- Execution order (user before project)
- No approval required for user hooks
- `--no-verify` skips all hooks
- Failure handling and behavior
- Template variable expansion
- Background hook execution
- Combined user and project hook scenarios
* Refine hooks: document remote_url, consolidate check
- Document remote_url template variable in cli.rs (syncs to docs)
- Move check_any_hook_configured into run_hook_with_filter
- Simplify standalone hook match arms
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Update snapshots for symmetric project hook labeling
Project hooks now show "project" prefix (e.g., "Running project pre-merge")
for consistency with user hook labeling.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Update docs to reflect user hooks in all hook references
- wt hook intro: Mention both user and project hooks
- --no-verify: Change "skip project hooks" to "skip all hooks"
- User config comment: Clarify verify skips all hooks
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Add `wt hook show` command to display configured hooks with approval status
Adds a new `show` subcommand to `wt hook` that displays all configured hooks
from both user and project config files with their approval status. Project
hooks show a ❓ indicator when they require approval.
Features:
- Lists hooks organized by type (post-create, post-start, pre-commit, etc.)
- Shows both user-level hooks (run for all repos) and project-specific hooks
- Displays approval status for project hooks (❓ = needs approval)
- Optional `--expanded` flag to show template variables substituted with current context
- Optional hook type filter to show only specific hook types
- Output is displayed through a pager (like git help) when available
Also reorders hook subcommands to put `show` first, making hook inspection
the primary entry point before hook execution commands.
* feat: Add user-level hooks that run for all repositories
Personal hooks in ~/.config/worktrunk/config.toml now run automatically
before project hooks for all worktree operations. User hooks don't require
approval and use the same syntax and template variables as project hooks.
Changes:
- Add user hook support for all hook types (post-create, post-start,
pre-commit, pre-merge, post-merge, pre-remove)
- User hooks run before project hooks in execution order
- Skip all hooks with --no-verify (applies to both user and project)
- Add remote_url template variable for repository-aware filtering
- Update documentation and help text to reflect user hooks
- Refine hook labeling to distinguish "user" vs "project" hooks in output
- Add comprehensive integration tests for user hook functionality
* feat: Add user-level hooks and improve hook infrastructure
User hooks enable personal, repository-agnostic automations while maintaining
team standards via project hooks. Key improvements:
- User hooks defined in ~/.config/worktrunk/config.toml run before project hooks
- User hooks don't require approval (user implicitly approves by defining them)
- Post-start logs now include source prefix to avoid collisions (user/project)
- remote_url template variable added for conditional hook logic
- Hook output labels distinguish user vs project hooks for clarity
- All hooks skipped together via --no-verify flag
- --no-verify help text simplified from "Skip project hooks" to "Skip hooks"
Implementation:
- HookSource enum tracks whether hooks are user or project
- prepare_user_commands() handles user hooks (no approval needed)
- Hook pipeline shows source in output: "Running user pre-merge" vs "Running project pre-merge"
- Background operation names include source to prevent log file collisions
* feat: support SSH URLs and improve branch name escaping
Add support for ssh:// URL format in git remote parsing to handle
SSH URLs alongside existing git@ and https:// formats.
Improve branch name escaping for git config keys by using hex encoding
(-XX format) instead of percent-encoding, ensuring all non-alphanumeric
characters (except . and -) are properly escaped. This handles UTF-8
multi-byte sequences and enables reliable round-trip encoding/decoding
of branch names containing /, _, and other special characters.
* feat: Add user-level hooks and improve hook infrastructure
User hooks enable personal, repository-agnostic automations while maintaining
team standards via project hooks. Key improvements:
- User hooks defined in ~/.config/worktrunk/config.toml run before project hooks
- User hooks don't require approval (user implicitly approves by defining them)
- Post-start logs now include source prefix to avoid collisions (user/project)
- remote_url template variable added for conditional hook logic
- Hook output labels distinguish user vs project hooks for clarity
- All hooks skipped together via --no-verify flag
- --no-verify help text simplified from "Skip project hooks" to "Skip hooks"
Implementation:
- HookSource enum tracks whether hooks are user or project
- prepare_user_commands() handles user hooks (no approval needed)
- Hook pipeline shows source in output: "Running user pre-merge" vs "Running project pre-merge"
- Background operation names include source to prevent log file collisions
* Fix pre-remove hook approval with "Approve at the Gate" pattern
The pre-remove hook execution was incorrectly using auto_trust=true,
bypassing approval prompts. This commit introduces a design pattern
where approval happens exactly once at command entry points:
- Add collect_and_approve_hooks() helper for upfront approval
- wt remove now approves pre-remove hooks before any execution
- Add --force flag to skip approval prompts
- Thread auto_trust parameter through handle_remove_output
The pattern ensures approval happens at the "gate" (command entry),
eliminating error-prone threading of auto_trust through execution layers.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Remove pending snapshot file from statusline tests
The .statusline.rs.pending-snap file is no longer needed and should not be committed to version control.
* Implement "Approve at the Gate" pattern for all project hooks
Moves approval prompts to command entry points instead of hook execution.
Commands are now approved once in a batch before any hooks run, with template
expansion so users see actual values (branch names, paths) instead of
placeholders. This eliminates redundant prompts and simplifies the execution
layer by removing the `auto_trust` parameter threading.
Key changes:
- Rename `collect_and_approve_hooks()` to `collect_and_approve_hooks_with_context()`
and add `expand_commands_for_approval()` for showing expanded templates in prompts
- Remove `auto_trust` parameter from hook execution functions
- Simplify `HookSource::Project` enum variant (no longer carries approval state)
- Add gate approval at `wt switch --create`, `wt remove`, `wt step commit/squash`
- Update merge command collection to expand templates before approval batch
- Remove binary `rust_out` artifact and test snapshot file
* Clarify hook command runs on demand for testing and CI
Update documentation and help text to better explain that `wt hook`
runs hooks independently of normal worktree operations. Changes emphasize
the use cases (testing, CI, re-running after failure) rather than
describing it as "manually" running hooks.
Also simplify phrasing around user hooks and remove unnecessary markdown
formatting for consistency.
* Rename approval and hook functions to simpler names
Update function names to be more concise and consistent:
- `collect_and_approve_hooks_with_context()` → `approve_hooks()`
- `handle_standalone_run_hook()` → `run_hook()`
- `handle_standalone_commit()` → `step_commit()`
- `handle_standalone_add_approvals()` → `add_approvals()`
- `handle_standalone_clear_approvals()` → `clear_approvals()`
Also update documentation examples to reference the new names.
* Handle declined command approvals by skipping hooks while continuing operations
When users decline command approval, hooks are now skipped but the operation
proceeds. This applies consistently across all approval gates: merge, commit,
squash, remove, and hook execution.
Previously, declined approvals would still attempt hook execution. Now, the
verify flag is shadowed based on approval result - if declined, verify becomes
false to gate all subsequent hook execution. For explicit hook runs via
`wt hook`, a declined approval returns early since the entire purpose is hook
execution.
This ensures users have clear control: approving runs hooks, declining skips
them but continues the workflow.
* Fix wt hook approval: filter by name and use consistent target branch
Two fixes for `wt hook` command:
1. Pass name_filter to approval so `wt hook pre-merge --name foo` only
prompts for approval of the "foo" hook, not all hooks of that type.
Added `approve_hooks_filtered()` function that accepts optional name
filter parameter.
2. Use current branch as target for pre-merge/post-merge approval prompts
to match execution. Previously approval used default_branch while
execution used current branch, showing misleading command expansions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix wt hook show --expanded to expand {{ target }} for merge/commit hooks
The expand_command_template function now passes hook-specific extra vars:
- PreCommit: target = default branch (for comparison context)
- PreMerge/PostMerge: target = current branch (matches run_hook behavior)
Previously, --expanded would show raw {{ target }} placeholders for these
hook types because extra_vars was always empty.
Also added TODO for pre-remove approval context issue: when removing
another worktree, the approval preview uses current worktree context
instead of the target worktree context.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Add `wrap_help` feature to clap and `terminal_size` dependency to enable
automatic wrapping of help text based on terminal width. This improves
readability of long help descriptions by breaking them across multiple lines
instead of displaying as a single long line.
Changes:
- Enable `wrap_help` feature in clap configuration
- Add `terminal_size` crate as dependency for detecting terminal dimensions
- Update help template to support wrapping with proper formatting
- Help snapshots now show wrapped text at 150 character column width
Separate the "same commit" case (branch HEAD == main) from "ancestor"
case (branch is ancestor of main but main has moved past) to enable
distinct status symbols. Update symbol from `·` to `_` for clarity and
add `Ancestor` variant to `IntegrationReason` enum. Branches that are
ancestors now show `⊂` (integrated) instead of `_` (same commit).
Command pages now preserve frontmatter in skeleton files (title, weight, group)
and replace only the AUTO-GENERATED marker region during sync. The END tag
mirrors the source ID to unambiguously match regions even with nested markers.
This allows manual editing of frontmatter and conceptual docs while keeping
auto-generated content synchronized. The main.rs generator outputs just the
content between START and END markers, and the sync test uses regex to find
and replace the exact region.
Improve branch cleanup detection with four ordered checks to identify when
branch content is already in the target branch. This enables accurate removal
of squash-merged branches even after target advances.
**New integration checks (in cost order):**
- Same commit: Branch HEAD is literally the same commit as target
- No added changes: Three-dot diff shows no file changes beyond merge-base
- Tree contents match: Tree SHA equals target's tree SHA
- Merge simulation: Merging branch into target adds nothing (--full only)
**Status symbols updated:**
- `·` for same commit (cheapest check)
- `⊂` for content integrated via different history (all other cases)
Previously used `≡` (matches main) and `_` (no commits) which were ambiguous.
The new symbols better represent the checked conditions.
**Implementation:**
- Add `IsAncestorTask`, `HasFileChangesTask`, `WouldMergeAddTask` to task DAG
- Add `is_ancestor`, `has_file_changes`, `would_merge_add` fields to `ListItem`
- Create `IntegrationReason` enum for type-safe reason tracking
- Update `is_potentially_removable()` logic with ordered checks
- Refine `BranchOpState` variants to map to integration reasons
Implement pre-remove hooks that run before `wt remove` deletes a worktree.
This allows cleanup tasks, state saving, or external notifications before
removal. Key features:
- FailFast strategy: non-zero exit code aborts removal (worktree preserved)
- Runs in both sync and background modes (before spawning background)
- All standard template variables available (branch, worktree, repo, etc.)
- Does not run for branch-only removal (no worktree)
- Skip with `--no-verify` flag
- Run manually with `wt step pre-remove`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Replace "Branch is ancestor" with "No added changes" to better describe the three-dot diff check. Rename has_marginal_contribution to has_added_changes for clarity about what the method actually checks. Update documentation and integration reason enum to reflect the actual behavior: detecting file changes beyond the merge-base rather than testing ancestry.
Configuration section now distinguishes between command behavior and defaults, with clearer explanations of what each setting controls. Hooks documentation expanded to explain the three branch cleanup conditions checked before safe deletion, with examples using `{{ repo_root }}` variable.
LLM commits section clarified to show squash-merge workflow as the primary use case. Claude Code statusline explanation expanded on network latency and async suitability. Branch state symbol `_` redefined as "no commits ahead" rather than "empty branch" to better reflect actual behavior.
Updated `wt remove` documentation to cross-reference FAQ instead of switch.md, and simplified tips section by linking to switch.md shortcuts instead of duplicating the list.
- Add horizontal scrolling and consistent styling to images in documentation
- Update remove command help text to clarify argument resolution and shortcuts
* Standardize doc headings to sentence case
Use sentence case for all documentation headings, matching modern
technical documentation conventions (GitHub, Stripe, Tailwind).
Exceptions preserved:
- Proper nouns: Claude Code, Worktrunk, Node.js, Python, Rust
- Acronyms: LLM, CI, JSON, API, CLI
- Code/commands: wt merge, post-create (stay lowercase)
- Questions: "Why Worktrunk?" (natural casing)
Changes span both manual docs and CLI help text (via cli.rs), with
auto-generated command pages regenerated to match.
* Update README and test snapshots for sentence case headings
Update auto-generated README sections and test snapshots to match
the sentence case heading changes in the previous commit.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Increase PTY drain wait to fix flaky Ubuntu CI test
The test_list_progressive_many_worktrees test was failing intermittently
on Ubuntu CI because 500ms wasn't enough time for the kernel to flush
all PTY buffer data under load. Increased MIN_DRAIN_WAIT_MS to 1000ms
to provide more margin for slow CI runners with many worktrees.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Removes duplicated explanation of argument resolution behavior from
remove command docs and replaces with cross-reference to switch command
where this pattern is described. Also renames "When Branches Are Deleted"
section to "Branch Cleanup" for clarity.
Update documentation to use Zola's native link handling instead of
standard markdown syntax for better site navigation and consistency.
This improves link resolution within the documentation system.
Reorder switch command documentation to place "Creating Worktrees" before
"Shortcuts" for better logical flow. Add auto-generated header comments to all
command docs (switch, list, merge, remove, select, config, step) to indicate
they're generated from CLI help. Adjust command weights in navigation to reflect
workflow order: switch, list, remove, merge, then utilities.
Command output blocks don't require language specification and render
correctly without it. Removing `bash` from the markdown fence makes
the markup cleaner and more semantically accurate.
Update help text and documentation across all commands to improve clarity:
- Simplify introductory descriptions to focus on what commands do, not why
- Reorganize status symbol tables into logical groups (working tree, branch, divergence, remote, other)
- Consolidate column descriptions for better readability
- Rewrite sections to use active voice and concrete language
- Add "See Also" cross-references to related commands
- Streamline examples to be more concise with inline comments
- Improve JSON query examples with shorter descriptions
- Clarify hook behavior descriptions without assuming user intent
- Update help snapshots to reflect documentation changes
Reorganize command documentation (switch, list, merge, remove, select, config, step)
for consistency and clarity. Restructure around user tasks: intro, examples, features,
then technical details. Update CLAUDE.md with documentation guidelines.
Add `test_command_pages_are_in_sync()` integration test to auto-update command pages
when `wt <cmd> --help-page` output changes, eliminating manual regeneration.
Update docs/CLAUDE.md to document the new sync test workflow instead of manual
regeneration steps.
Add dedicated documentation pages for each command (switch, list, merge,
remove, select, config, step) generated from CLI help text via new
--help-page flag. Pages include prose documentation from after_long_help
and command reference at bottom.
- Add --help-page flag to main.rs for generating doc pages
- Create individual command pages with Zola frontmatter
- Add sidebar grouping (Commands/Reference) via page.extra.group
- Update page.html template to render group labels
- Delete monolithic commands.md in favor of individual pages
- Tighten TOC spacing for child items
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Maximilian Roos