Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
fix: Increase timeout for flaky macOS CI test (#38)
Maximilian Roos84eb28ed6c04
diff --git a/README.md b/README.mdindex 2346af330..b32edc5d0 100644--- a/README.md+++ b/README.md@@ -305,7 +305,7 @@ instead of duplicating logic:<summary><strong><code>wt switch [branch]</code></strong> - Switch to existing worktree or create a new one</summary><!-- README:help:wt switch --help-md -->-```+```textwt switch — Switch to a worktreeUsage: switch [OPTIONS] <BRANCH>@@ -335,6 +335,7 @@ Options:Print help (see a summary with '-h')```+## Operation### Switching to Existing Worktree@@ -344,6 +345,7 @@ Options:- No branch creation### Creating New Worktree (`--create`)+1. Creates new branch (defaults to current default branch as base)2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)3. Runs post-create hooks sequentially (blocking)@@ -361,6 +363,7 @@ Options:- Skip with `--no-verify`### post-start (parallel, background)+- Spawned after success message shown- Typically: dev servers, file watchers, editors- Run in background, failures logged but don't block@@ -376,31 +379,37 @@ See `wt config approvals --help`.## ExamplesSwitch to existing worktree:+```bashwt switch feature-branch```Create new worktree from main:+```bashwt switch --create new-feature```Switch to previous worktree:+```bashwt switch -```Create from specific base:+```bashwt switch --create hotfix --base production```Create and run command:+```bashwt switch --create docs --execute "code ."```Skip hooks during creation:+```bashwt switch --create temp --no-verify```@@ -408,6 +417,7 @@ wt switch --create temp --no-verify## ShortcutsUse `@` for current HEAD, `-` for previous, `^` for main:+```bashwt switch @ # Switch to current branch's worktreewt switch - # Switch to previous worktree@@ -423,7 +433,7 @@ wt remove @ # Remove current worktree<summary><strong><code>wt merge [target]</code></strong> - Merge, push, and cleanup</summary><!-- README:help:wt merge --help-md -->-```+```textwt merge — Merge worktree into target branchUsage: merge [OPTIONS] [TARGET]@@ -461,6 +471,7 @@ Options:Print help (see a summary with '-h')```+## OperationCommit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks@@ -501,21 +512,25 @@ See `wt config approvals --help`.## ExamplesBasic merge to main:+```bashwt merge```Merge without squashing:+```bashwt merge --no-squash```Keep worktree after merging:+```bashwt merge --no-remove```Skip all hooks:+```bashwt merge --no-verify```@@ -527,7 +542,7 @@ wt merge --no-verify<summary><strong><code>wt remove [worktree]</code></strong> - Remove worktree and branch</summary><!-- README:help:wt remove --help-md -->-```+```textwt remove — Remove worktree and branchUsage: remove [OPTIONS] [WORKTREES]...@@ -549,6 +564,7 @@ Options:Print help (see a summary with '-h')```+## OperationRemoves worktree directory, git metadata, and branch. Requires clean working tree.@@ -576,31 +592,37 @@ Stops any git fsmonitor daemon for the worktree before removal. This prevents or## ExamplesRemove current worktree and branch:+```bashwt remove```Remove specific worktree and branch:+```bashwt remove feature-branch```Remove worktree but keep branch:+```bashwt remove --no-delete-branch feature-branch```Remove multiple worktrees:+```bashwt remove old-feature another-branch```Remove in foreground (blocking):+```bashwt remove --no-background feature-branch```Switch to default in main:+```bashwt remove # (when already in main worktree)```@@ -612,7 +634,7 @@ wt remove # (when already in main worktree)<summary><strong><code>wt list</code></strong> - Show all worktrees and branches</summary><!-- README:help:wt list --help-md -->-```+```textwt list — List worktrees and optionally branchesUsage: list [OPTIONS]@@ -640,6 +662,7 @@ Options:Print help (see a summary with '-h')```+## Columns- **Branch:** Branch name@@ -694,6 +717,7 @@ Use `--format=json` for structured data. Each object contains two status mapswith the same fields in the same order as Status Symbols above:**`status`** - variant names for querying:+- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`- `git_operation`: `""` | `"Rebase"` | `"Merge"`@@ -731,7 +755,7 @@ jq '.[] | select(.locked != null)'<summary><strong><code>wt config</code></strong> - Manage configuration</summary><!-- README:help:wt config --help-md -->-```+```textwt config — Manage configuration and shell integrationUsage: config <COMMAND>@@ -749,19 +773,23 @@ Options:Print help (see a summary with '-h')```+## Setup Guide1. Set up shell integration+```bashwt config shell install```Or manually add to your shell config:+```basheval "$(wt config shell init bash)"```2. (Optional) Create config file+```bashwt config create```@@ -773,14 +801,16 @@ Options:Install: `uv tool install -U llm`Configure: `llm keys set anthropic`Add to config.toml:+```toml[commit-generation]command = "llm"- ```bash+ ```## LLM Setup DetailsFor Claude:+```bashllm install llm-anthropicllm keys set anthropic@@ -788,20 +818,23 @@ llm models default claude-3.5-sonnet```For OpenAI:+```bashllm keys set openai```Use `wt config list` to view your current configuration.-Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat+Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>## Configuration Files**Global config** (user settings):+- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)- Run `wt config create --help` to view documented examples**Project config** (repository hooks):+- Location: `.config/wt.toml` in repository root- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks<!-- README:end -->@@ -812,7 +845,7 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat<summary><strong><code>wt step</code></strong> - Building blocks for workflows</summary><!-- README:help:wt step --help-md -->-```+```textwt step — Primitive operations (building blocks for workflows)Usage: step <COMMAND>@@ -923,28 +956,6 @@ The most helpful way to contribute:- Star the repo / tell friends / post about it- Find bugs, file reproducible bug reports-<details>-<summary>Developing</summary>--### Releases--Use [cargo-release](https://github.com/crate-ci/cargo-release) to publish new versions:--```bash-cargo install cargo-release--# Bump version, update Cargo.lock, commit, tag, and push-cargo release patch --execute # 0.1.0 -> 0.1.1-cargo release minor --execute # 0.1.0 -> 0.2.0-cargo release major --execute # 0.1.0 -> 1.0.0-```--This updates Cargo.toml and Cargo.lock, creates a commit and tag, then pushes to GitHub. The tag push triggers GitHub Actions to build binaries, create the release, and publish to crates.io.--Run without `--execute` to preview changes first.--</details>-## FAQ<details>@@ -984,13 +995,13 @@ Use `--force` to bypass prompts (useful for CI/automation).<details><summary><strong>How does Worktrunk compare to alternatives?</strong></summary>-#### vs. Branch Switching+### vs. Branch Switching`git checkout` forces all work through a single directory. Switching branches means rebuilding artifacts, restarting dev servers, and stashing changes. Only one branch can be active at a time.Worktrunk gives each branch its own directory with independent build caches, processes, and editor state. Work on multiple branches simultaneously without rebuilding or stashing.-#### vs. Plain `git worktree`+### vs. Plain `git worktree`Git's built-in worktree commands work but require manual lifecycle management:@@ -1021,7 +1032,7 @@ What `git worktree` doesn't provide:Worktrunk adds path management, lifecycle hooks, and `wt list --full` for viewing all worktrees—branches, uncommitted changes, commits ahead/behind, CI status, and conflicts—in a single view.-#### vs. git-machete / git-town+### vs. git-machete / git-townDifferent scopes:@@ -1031,7 +1042,7 @@ Different scopes:These tools can be used together—run git-machete or git-town inside individual worktrees.-#### vs. Git TUIs (lazygit, gh-dash, etc.)+### vs. Git TUIs (lazygit, gh-dash, etc.)Git TUIs operate on a single repository. Worktrunk manages multiple worktrees, runs automation hooks, and aggregates status across branches (`wt list --full`). Use your preferred TUI inside each worktree directory.@@ -1049,3 +1060,25 @@ cargo install worktrunk --no-default-featuresThis disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.</details>++<details>+<summary>Developing</summary>++### Releases++Use [cargo-release](https://github.com/crate-ci/cargo-release) to publish new versions:++```bash+cargo install cargo-release++# Bump version, update Cargo.lock, commit, tag, and push+cargo release patch --execute # 0.1.0 -> 0.1.1+cargo release minor --execute # 0.1.0 -> 0.2.0+cargo release major --execute # 0.1.0 -> 1.0.0+```++This updates Cargo.toml and Cargo.lock, creates a commit and tag, then pushes to GitHub. The tag push triggers GitHub Actions to build binaries, create the release, and publish to crates.io.++Run without `--execute` to preview changes first.++</details>diff --git a/src/cli.rs b/src/cli.rsindex 75958d360..53f492ae7 100644--- a/src/cli.rs+++ b/src/cli.rs@@ -507,16 +507,19 @@ pub enum Commands {after_long_help = r#"## Setup Guide1. Set up shell integration+```bashwt config shell install```Or manually add to your shell config:+```basheval "$(wt config shell init bash)"```2. (Optional) Create config file+```bashwt config create```@@ -528,14 +531,16 @@ pub enum Commands {Install: `uv tool install -U llm`Configure: `llm keys set anthropic`Add to config.toml:+```toml[commit-generation]command = "llm"- ```bash+ ```## LLM Setup DetailsFor Claude:+```bashllm install llm-anthropicllm keys set anthropic@@ -543,20 +548,23 @@ llm models default claude-3.5-sonnet```For OpenAI:+```bashllm keys set openai```Use `wt config list` to view your current configuration.-Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat+Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>## Configuration Files**Global config** (user settings):+- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)- Run `wt config create --help` to view documented examples**Project config** (repository hooks):+- Location: `.config/wt.toml` in repository root- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks"#@@ -635,6 +643,7 @@ Use `--format=json` for structured data. Each object contains two status mapswith the same fields in the same order as Status Symbols above:**`status`** - variant names for querying:+- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans- `branch_state`: `\"\"` | `\"Conflicts\"` | `\"MergeTreeConflicts\"` | `\"MatchesMain\"` | `\"NoCommits\"`- `git_operation`: `\"\"` | `\"Rebase\"` | `\"Merge\"`@@ -703,6 +712,7 @@ jq '.[] | select(.locked != null)'- No branch creation### Creating New Worktree (`--create`)+1. Creates new branch (defaults to current default branch as base)2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)3. Runs post-create hooks sequentially (blocking)@@ -720,6 +730,7 @@ jq '.[] | select(.locked != null)'- Skip with `--no-verify`### post-start (parallel, background)+- Spawned after success message shown- Typically: dev servers, file watchers, editors- Run in background, failures logged but don't block@@ -735,31 +746,37 @@ See `wt config approvals --help`.## ExamplesSwitch to existing worktree:+```bashwt switch feature-branch```Create new worktree from main:+```bashwt switch --create new-feature```Switch to previous worktree:+```bashwt switch -```Create from specific base:+```bashwt switch --create hotfix --base production```Create and run command:+```bashwt switch --create docs --execute "code ."```Skip hooks during creation:+```bashwt switch --create temp --no-verify```@@ -767,6 +784,7 @@ wt switch --create temp --no-verify## ShortcutsUse `@` for current HEAD, `-` for previous, `^` for main:+```bashwt switch @ # Switch to current branch's worktreewt switch - # Switch to previous worktree@@ -830,31 +848,37 @@ Stops any git fsmonitor daemon for the worktree before removal. This prevents or## ExamplesRemove current worktree and branch:+```bashwt remove```Remove specific worktree and branch:+```bashwt remove feature-branch```Remove worktree but keep branch:+```bashwt remove --no-delete-branch feature-branch```Remove multiple worktrees:+```bashwt remove old-feature another-branch```Remove in foreground (blocking):+```bashwt remove --no-background feature-branch```Switch to default in main:+```bashwt remove # (when already in main worktree)```"#)]@@ -917,21 +941,25 @@ See `wt config approvals --help`.## ExamplesBasic merge to main:+```bashwt merge```Merge without squashing:+```bashwt merge --no-squash```Keep worktree after merging:+```bashwt merge --no-remove```Skip all hooks:+```bashwt merge --no-verify```"#)]diff --git a/tests/integration_tests/post_start_commands.rs b/tests/integration_tests/post_start_commands.rsindex cccdd209c..089e0c1c4 100644--- a/tests/integration_tests/post_start_commands.rs+++ b/tests/integration_tests/post_start_commands.rs@@ -15,8 +15,8 @@ const SLEEP_FAST_COMMAND: Duration = Duration::from_millis(100);const SLEEP_BACKGROUND_COMMAND: Duration = Duration::from_millis(200);/// Extended wait for commands that include explicit sleep in the command itself-/// (e.g., "sleep 0.1 && echo ..." requires at least 100ms + margin)-const SLEEP_EXTENDED: Duration = Duration::from_millis(250);+/// (e.g., "sleep 0.1 && echo ..." requires at least 100ms + margin for CI overhead)+const SLEEP_EXTENDED: Duration = Duration::from_millis(500);/// Helper to create snapshot with normalized paths and SHAs///diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 61fd8142a..d2467b639 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -212,15 +212,11 @@ fn get_help_output(command: &str, project_root: &Path) -> Result<String, String>if let Some(header_pos) = rest.find("\n## ") {// Split at first H2 headerlet (synopsis, docs) = rest.split_at(header_pos);- format!(- "```\n{}{}\n```\n{}",- first_line,- synopsis,- docs.trim_start_matches('\n')- )+ let docs = docs.trim_start_matches('\n');+ format!("```text\n{}{}\n```\n\n{}", first_line, synopsis, docs)} else {// No documentation section, wrap everything in code block- format!("```\n{}{}\n```", first_line, rest)+ format!("```text\n{}{}\n```", first_line, rest)}} else {// Single line outputdiff --git a/tests/snapshots/integration__integration_tests__help__help_config.snap b/tests/snapshots/integration__integration_tests__help__help_config.snapindex 43722cb96..fbeeba77e 100644--- a/tests/snapshots/integration__integration_tests__help__help_config.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config.snap@@ -42,12 +42,15 @@ Global Options:[32mSetup Guide[0m1. Set up shell integration+[2m wt config shell install[0mOr manually add to your shell config:+[2m eval "$(wt config shell init bash)"[0m2. (Optional) Create config file+[2m wt config create[0mThis creates ~/.config/worktrunk/config.toml with examples.@@ -57,29 +60,34 @@ Global Options:Install: [2muv tool install -U llm[0mConfigure: [2mllm keys set anthropic[0mAdd to config.toml:+[2m [commit-generation][0m[2m command = "llm"[0m[32mLLM Setup Details[0mFor Claude:+[2mllm install llm-anthropic[0m[2mllm keys set anthropic[0m[2mllm models default claude-3.5-sonnet[0mFor OpenAI:+[2mllm keys set openai[0mUse [2mwt config list[0m to view your current configuration.-Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat+Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>[32mConfiguration Files[0m[1mGlobal config[0m (user settings):+- Location: [2m~/.config/worktrunk/config.toml[0m (or [2mWORKTRUNK_CONFIG_PATH[0m)- Run [2mwt config create --help[0m to view documented examples[1mProject config[0m (repository hooks):+- Location: [2m.config/wt.toml[0m in repository root- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooksdiff --git a/tests/snapshots/integration__integration_tests__help__help_list.snap b/tests/snapshots/integration__integration_tests__help__help_list.snapindex e1097428c..f52ae88b0 100644--- a/tests/snapshots/integration__integration_tests__help__help_list.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list.snap@@ -104,6 +104,7 @@ Use [2m--format=json[0m for structured data. Each object contains two status mwith the same fields in the same order as Status Symbols above:[1m`status`[0m - variant names for querying:+- [2mworking_tree[0m: [2m{untracked, modified, staged, renamed, deleted}[0m booleans- [2mbranch_state[0m: [2m""[0m | [2m"Conflicts"[0m | [2m"MergeTreeConflicts"[0m | [2m"MatchesMain"[0m | [2m"NoCommits"[0m- [2mgit_operation[0m: [2m""[0m | [2m"Rebase"[0m | [2m"Merge"[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snapindex 235209355..36bc90abf 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge.snap@@ -100,15 +100,19 @@ See [2mwt config approvals --help[0m.[32mExamples[0mBasic merge to main:+[2mwt merge[0mMerge without squashing:+[2mwt merge --no-squash[0mKeep worktree after merging:+[2mwt merge --no-remove[0mSkip all hooks:+[2mwt merge --no-verify[0m----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__help__help_remove.snap b/tests/snapshots/integration__integration_tests__help__help_remove.snapindex c52667993..3d0c40e11 100644--- a/tests/snapshots/integration__integration_tests__help__help_remove.snap+++ b/tests/snapshots/integration__integration_tests__help__help_remove.snap@@ -71,21 +71,27 @@ Stops any git fsmonitor daemon for the worktree before removal. This prevents or[32mExamples[0mRemove current worktree and branch:+[2mwt remove[0mRemove specific worktree and branch:+[2mwt remove feature-branch[0mRemove worktree but keep branch:+[2mwt remove --no-delete-branch feature-branch[0mRemove multiple worktrees:+[2mwt remove old-feature another-branch[0mRemove in foreground (blocking):+[2mwt remove --no-background feature-branch[0mSwitch to default in main:+[2mwt remove # (when already in main worktree)[0m----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snapindex 67679a9d6..49ce59f8c 100644--- a/tests/snapshots/integration__integration_tests__help__help_switch.snap+++ b/tests/snapshots/integration__integration_tests__help__help_switch.snap@@ -61,6 +61,7 @@ Global Options:- No branch creation### Creating New Worktree ([2m--create[0m)+1. Creates new branch (defaults to current default branch as base)2. Creates worktree in configured location (default: [2m../{{ main_worktree }}.{{ branch }}[0m)3. Runs post-create hooks sequentially (blocking)@@ -78,6 +79,7 @@ Global Options:- Skip with [2m--no-verify[0m### post-start (parallel, background)+- Spawned after success message shown- Typically: dev servers, file watchers, editors- Run in background, failures logged but don't block@@ -93,26 +95,33 @@ See [2mwt config approvals --help[0m.[32mExamples[0mSwitch to existing worktree:+[2mwt switch feature-branch[0mCreate new worktree from main:+[2mwt switch --create new-feature[0mSwitch to previous worktree:+[2mwt switch -[0mCreate from specific base:+[2mwt switch --create hotfix --base production[0mCreate and run command:+[2mwt switch --create docs --execute "code ."[0mSkip hooks during creation:+[2mwt switch --create temp --no-verify[0m[32mShortcuts[0mUse [2m@[0m for current HEAD, [2m-[0m for previous, [2m^[0m for main:+[2mwt switch @ # Switch to current branch's worktree[0m[2mwt switch - # Switch to previous worktree[0m[2mwt switch --create new-feature --base=^ # Branch from main (default)[0m