Skip to content

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.md
index 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 -->
-```
+```text
wt switch — Switch to a worktree
Usage: 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`.
## Examples
Switch to existing worktree:
+
```bash
wt switch feature-branch
```
Create new worktree from main:
+
```bash
wt switch --create new-feature
```
Switch to previous worktree:
+
```bash
wt switch -
```
Create from specific base:
+
```bash
wt switch --create hotfix --base production
```
Create and run command:
+
```bash
wt switch --create docs --execute "code ."
```
Skip hooks during creation:
+
```bash
wt switch --create temp --no-verify
```
@@ -408,6 +417,7 @@ wt switch --create temp --no-verify
## Shortcuts
Use `@` for current HEAD, `-` for previous, `^` for main:
+
```bash
wt switch @ # Switch to current branch's worktree
wt 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 -->
-```
+```text
wt merge — Merge worktree into target branch
Usage: merge [OPTIONS] [TARGET]
@@ -461,6 +471,7 @@ Options:
Print help (see a summary with '-h')
```
+
## Operation
Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
@@ -501,21 +512,25 @@ See `wt config approvals --help`.
## Examples
Basic merge to main:
+
```bash
wt merge
```
Merge without squashing:
+
```bash
wt merge --no-squash
```
Keep worktree after merging:
+
```bash
wt merge --no-remove
```
Skip all hooks:
+
```bash
wt 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 -->
-```
+```text
wt remove — Remove worktree and branch
Usage: remove [OPTIONS] [WORKTREES]...
@@ -549,6 +564,7 @@ Options:
Print help (see a summary with '-h')
```
+
## Operation
Removes 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
## Examples
Remove current worktree and branch:
+
```bash
wt remove
```
Remove specific worktree and branch:
+
```bash
wt remove feature-branch
```
Remove worktree but keep branch:
+
```bash
wt remove --no-delete-branch feature-branch
```
Remove multiple worktrees:
+
```bash
wt remove old-feature another-branch
```
Remove in foreground (blocking):
+
```bash
wt remove --no-background feature-branch
```
Switch to default in main:
+
```bash
wt 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 -->
-```
+```text
wt list — List worktrees and optionally branches
Usage: 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 maps
with 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 -->
-```
+```text
wt config — Manage configuration and shell integration
Usage: config <COMMAND>
@@ -749,19 +773,23 @@ Options:
Print help (see a summary with '-h')
```
+
## Setup Guide
1. Set up shell integration
+
```bash
wt config shell install
```
Or manually add to your shell config:
+
```bash
eval "$(wt config shell init bash)"
```
2. (Optional) Create config file
+
```bash
wt 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 Details
For Claude:
+
```bash
llm install llm-anthropic
llm keys set anthropic
@@ -788,20 +818,23 @@ llm models default claude-3.5-sonnet
```
For OpenAI:
+
```bash
llm 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 -->
-```
+```text
wt 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-town
Different 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-features
This 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.rs
index 75958d360..53f492ae7 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -507,16 +507,19 @@ pub enum Commands {
after_long_help = r#"## Setup Guide
1. Set up shell integration
+
```bash
wt config shell install
```
Or manually add to your shell config:
+
```bash
eval "$(wt config shell init bash)"
```
2. (Optional) Create config file
+
```bash
wt 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 Details
For Claude:
+
```bash
llm install llm-anthropic
llm keys set anthropic
@@ -543,20 +548,23 @@ llm models default claude-3.5-sonnet
```
For OpenAI:
+
```bash
llm 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 maps
with 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`.
## Examples
Switch to existing worktree:
+
```bash
wt switch feature-branch
```
Create new worktree from main:
+
```bash
wt switch --create new-feature
```
Switch to previous worktree:
+
```bash
wt switch -
```
Create from specific base:
+
```bash
wt switch --create hotfix --base production
```
Create and run command:
+
```bash
wt switch --create docs --execute "code ."
```
Skip hooks during creation:
+
```bash
wt switch --create temp --no-verify
```
@@ -767,6 +784,7 @@ wt switch --create temp --no-verify
## Shortcuts
Use `@` for current HEAD, `-` for previous, `^` for main:
+
```bash
wt switch @ # Switch to current branch's worktree
wt switch - # Switch to previous worktree
@@ -830,31 +848,37 @@ Stops any git fsmonitor daemon for the worktree before removal. This prevents or
## Examples
Remove current worktree and branch:
+
```bash
wt remove
```
Remove specific worktree and branch:
+
```bash
wt remove feature-branch
```
Remove worktree but keep branch:
+
```bash
wt remove --no-delete-branch feature-branch
```
Remove multiple worktrees:
+
```bash
wt remove old-feature another-branch
```
Remove in foreground (blocking):
+
```bash
wt remove --no-background feature-branch
```
Switch to default in main:
+
```bash
wt remove # (when already in main worktree)
```"#)]
@@ -917,21 +941,25 @@ See `wt config approvals --help`.
## Examples
Basic merge to main:
+
```bash
wt merge
```
Merge without squashing:
+
```bash
wt merge --no-squash
```
Keep worktree after merging:
+
```bash
wt merge --no-remove
```
Skip all hooks:
+
```bash
wt merge --no-verify
```"#)]
diff --git a/tests/integration_tests/post_start_commands.rs b/tests/integration_tests/post_start_commands.rs
index 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.rs
index 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 header
let (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 output
diff --git a/tests/snapshots/integration__integration_tests__help__help_config.snap b/tests/snapshots/integration__integration_tests__help__help_config.snap
index 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:
Setup Guide
1. Set up shell integration
+
 wt config shell install
Or manually add to your shell config:
+
 eval "$(wt config shell init bash)"
2. (Optional) Create config file
+
 wt config create
This creates ~/.config/worktrunk/config.toml with examples.
@@ -57,29 +60,34 @@ Global Options:
Install: uv tool install -U llm
Configure: llm keys set anthropic
Add to config.toml:
+
 [commit-generation]
 command = "llm"
LLM Setup Details
For Claude:
+
llm install llm-anthropic
llm keys set anthropic
llm models default claude-3.5-sonnet
For OpenAI:
+
llm 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
diff --git a/tests/snapshots/integration__integration_tests__help__help_list.snap b/tests/snapshots/integration__integration_tests__help__help_list.snap
index 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 --format=json for structured data. Each object contains two status m
with 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"
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snap
index 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 wt config approvals --help.
Examples
Basic merge to main:
+
wt merge
Merge without squashing:
+
wt merge --no-squash
Keep worktree after merging:
+
wt merge --no-remove
Skip all hooks:
+
wt merge --no-verify
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove.snap b/tests/snapshots/integration__integration_tests__help__help_remove.snap
index 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
Examples
Remove current worktree and branch:
+
wt remove
Remove specific worktree and branch:
+
wt remove feature-branch
Remove worktree but keep branch:
+
wt remove --no-delete-branch feature-branch
Remove multiple worktrees:
+
wt remove old-feature another-branch
Remove in foreground (blocking):
+
wt remove --no-background feature-branch
Switch to default in main:
+
wt remove # (when already in main worktree)
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snap
index 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 (--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)
@@ -78,6 +79,7 @@ Global 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
@@ -93,26 +95,33 @@ See wt config approvals --help.
Examples
Switch to existing worktree:
+
wt switch feature-branch
Create new worktree from main:
+
wt switch --create new-feature
Switch to previous worktree:
+
wt switch -
Create from specific base:
+
wt switch --create hotfix --base production
Create and run command:
+
wt switch --create docs --execute "code ."
Skip hooks during creation:
+
wt switch --create temp --no-verify
Shortcuts
Use @ for current HEAD, - for previous, ^ for main:
+
wt switch @ # Switch to current branch's worktree
wt switch - # Switch to previous worktree
wt switch --create new-feature --base=^ # Branch from main (default)