Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: Update README Quick Start for `wt switch`
Maximilian Roos412a76876169
diff --git a/README.md b/README.mdindex 3043e5f55..a80287d94 100644--- a/README.md+++ b/README.md@@ -57,43 +57,50 @@ $ wt switch --create fix-authThis creates `../repo.fix-auth` on branch `fix-auth`.-### 3. Merge it+### 3. Switch between worktrees-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_switch_back.snap — edit source to update -->```console-$ wt merge-🔄 Merging 1 commit to main @ d29e0fd (no commit/squash/rebase needed)- * d29e0fd Implement JWT validation- auth.rs | 13 +++++++++++++- 1 file changed, 13 insertions(+)-✅ Merged to main (1 commit, 1 file, +13)-🔄 Removing fix-auth worktree & branch in background (ancestor of main)+$ wt switch feature-api+✅ Switched to worktree for feature-api at ../repo.feature-api```<!-- END AUTO-GENERATED -->-`wt merge` handles the full workflow: stage, commit, squash, rebase, run hooks,-merge, cleanup.-### 4. List worktrees+After doing some work:+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap — edit source to update -->```console$ wt list- Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message-@ main ^∥ ./repo ∥ b834638e 1d Initial commit-+ feature-x + ↑ +5 ↑3 ./repo.feature-x 6bba16d6 1h Add file 3-+ bugfix-y ↑ ↑1 ./repo.bugfix-y bafa4cbd 2h Fix bug+ Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message+@ feature-api + ↑ +3 ↑4 ./repo.feature-api 5b01afca 30m Add API tests+^ main ^∥ ./repo ∥ b834638e 1d Initial commit++ fix-auth _ ./repo.fix-auth b834638e 1d Initial commit-⚪ Showing 3 worktrees, 1 with changes, 2 ahead+⚪ Showing 3 worktrees, 1 with changes, 1 ahead```<!-- END AUTO-GENERATED -->`--full` adds CI status and conflicts. `--branches` includes all branches.+### 5. Clean up++Say we merged via CI, our changes are on main, and we're finished with the worktree:++<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_remove.snap — edit source to update -->++```console+$ wt remove+🔄 Removing feature-api worktree & branch in background+```++<!-- END AUTO-GENERATED -->+## Why worktrees?Parallel agents need isolated working directories that share one Git history.@@ -108,7 +115,7 @@ So we use git worktrees: multiple working directories backed by a single reposit## Why Worktrunk?-Git's built-in `worktree` commands give you the primitives but not the lifecycle. Worktrunk bundles creation, hooks, merging, and cleanup into three commands: `wt switch`, `wt merge`, and `wt list`. A few examples:+Git's built-in `worktree` commands give you the primitives but not the lifecycle. Worktrunk bundles creation, navigation, status, and cleanup into simple commands. A few examples:<table><tr>@@ -123,10 +130,9 @@ Git's built-in `worktree` commands give you the primitives but not the lifecyclecd ../repo.feature && claude</pre></td></tr><tr>-<td>Merge + clean up</td>-<td><pre lang="bash">wt merge</pre></td>-<td><pre lang="bash">cd ../repo && git merge feature-git worktree remove ../repo.feature+<td>Clean up</td>+<td><pre lang="bash">wt remove feature</pre></td>+<td><pre lang="bash">git worktree remove ../repo.featuregit branch -d feature</pre></td></tr><tr>@@ -148,7 +154,34 @@ cargo install --path .</pre></td></tr></table>-## Automation+## Advanced++Most Worktrunk users just use the commands above. But I've found these features really helpful too:++### Local merging with `wt merge`++`wt merge` handles the full merge workflow: stage, commit, squash, rebase, run hooks, merge, cleanup.++<table>+<tr>+<th>Task</th>+<th>Worktrunk</th>+<th>Plain git</th>+</tr>+<tr>+<td>Merge + clean up</td>+<td><pre lang="bash">wt merge</pre></td>+<td><pre lang="bash">git add -A+git reset --soft $(git merge-base HEAD main)+git diff --staged | llm "msg" | git commit -F -+git rebase main+cargo test # pre-merge hook+cd ../repo && git merge --ff-only feature+git worktree remove ../repo.feature+git branch -d feature+cargo install --path . # post-merge hook</pre></td>+</tr>+</table>### LLM commit messagesdiff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rsindex 4082b52d0..c4db24e0d 100644--- a/tests/integration_tests/list.rs+++ b/tests/integration_tests/list.rs@@ -1,4 +1,6 @@-use crate::common::{DAY, HOUR, TestRepo, list_snapshots, setup_snapshot_settings, wt_command};+use crate::common::{+ DAY, HOUR, MINUTE, TestRepo, list_snapshots, setup_snapshot_settings, wt_command,+};use insta::Settings;use insta_cmd::assert_cmd_snapshot;use std::path::Path;@@ -965,42 +967,45 @@ fn test_list_user_status_with_special_characters() {snapshot_list("user_status_special_chars", &repo);}-/// Generate README example: Simple list output showing multiple worktrees-/// This demonstrates the basic list output format used in the Quick Start section.+/// Generate README example: List output for Quick Start narrative+///+/// Shows main + fix-auth + feature-api worktrees (matches the Quick Start flow):+/// - fix-auth: just created, no commits ahead (same as main)+/// - feature-api: where we switched to and did work (commits ahead + staged changes)+////// Output: tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap#[test]fn test_readme_example_simple_list() {let mut repo = TestRepo::new();- // Initial commit on main - oldest (1 day ago)+ // Initial commit on main (yesterday)repo.commit_with_age("Initial commit", DAY);repo.setup_remote("main");- // Create worktrees with various states- let feature_x = repo.add_worktree("feature-x");- let bugfix_y = repo.add_worktree("bugfix-y");+ // Create fix-auth worktree (just created, no work yet - same commit as main)+ let _fix_auth = repo.add_worktree("fix-auth");- // feature-x: ahead with uncommitted changes (3 commits, most recent 10min ago)- repo.commit_with_age_in("Add file 1", 3 * HOUR, &feature_x);- repo.commit_with_age_in("Add file 2", 2 * HOUR, &feature_x);- repo.commit_with_age_in("Add file 3", HOUR, &feature_x);+ // Create feature-api worktree (existing work - we switched here and did work)+ let feature_api = repo.add_worktree("feature-api");- // Add staged changes (+5 lines)- std::fs::write(- feature_x.join("modified.txt"),- "line1\nline2\nline3\nline4\nline5\n",- )- .unwrap();+ // feature-api: several commits ahead with staged changes (a morning's work)+ repo.commit_with_age_in("Add REST endpoints", 3 * HOUR, &feature_api);+ repo.commit_with_age_in("Add authentication middleware", 2 * HOUR, &feature_api);+ repo.commit_with_age_in("Add request validation", HOUR, &feature_api);+ repo.commit_with_age_in("Add API tests", 30 * MINUTE, &feature_api);++ // Staged changes: a few more files in progress+ std::fs::write(feature_api.join("api.rs"), "// WIP: rate limiting\n").unwrap();+ std::fs::write(feature_api.join("middleware.rs"), "// WIP: caching\n").unwrap();+ std::fs::write(feature_api.join("tests.rs"), "// WIP: edge cases\n").unwrap();let mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);- cmd.args(["add", "modified.txt"])- .current_dir(&feature_x)+ cmd.args(["add", "api.rs", "middleware.rs", "tests.rs"])+ .current_dir(&feature_api).output().unwrap();- // bugfix-y: 1 commit ahead (2 hours ago), clean tree- repo.commit_with_age_in("Fix bug", 2 * HOUR, &bugfix_y);-- snapshot_list("readme_example_simple_list", &repo);+ // Run from feature-api (we just switched there in step 3)+ snapshot_list_from_dir("readme_example_simple_list", &repo, &feature_api);}#[test]diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex d8881bd2a..4fafb1739 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -37,10 +37,15 @@ static ANSI_LITERAL_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\[[0-/// Regex for HASH placeholder (used by shell_wrapper tests)static HASH_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\[HASH\]").unwrap());-/// Regex for TMPDIR paths-static TMPDIR_REGEX: LazyLock<Regex> =+/// Regex for TMPDIR paths with branch suffix (e.g., [TMPDIR]/repo.fix-auth)+static TMPDIR_BRANCH_REGEX: LazyLock<Regex> =LazyLock::new(|| Regex::new(r"\[TMPDIR\]/repo\.([^\s/]+)").unwrap());+/// Regex for TMPDIR paths without branch suffix (e.g., [TMPDIR]/repo at end or followed by space/newline)+/// Matches [TMPDIR]/repo when followed by end-of-string, whitespace, or non-word character (but not dot)+static TMPDIR_MAIN_REGEX: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r"\[TMPDIR\]/repo(\s|$)").unwrap());+/// Regex for REPO placeholderstatic REPO_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\[REPO\]").unwrap());@@ -241,7 +246,10 @@ fn trim_lines(content: &str) -> String {fn normalize_for_readme(content: &str) -> String {// Real SHAs flow through from deterministic tests (fixed dates + git identity)let content = HASH_REGEX.replace_all(content, "a1b2c3d");- let content = TMPDIR_REGEX.replace_all(&content, "../repo.$1");+ // Replace branch worktree paths first (e.g., [TMPDIR]/repo.fix-auth -> ../repo.fix-auth)+ let content = TMPDIR_BRANCH_REGEX.replace_all(&content, "../repo.$1");+ // Replace main worktree paths (e.g., [TMPDIR]/repo -> ../repo), preserving trailing whitespace+ let content = TMPDIR_MAIN_REGEX.replace_all(&content, "../repo$1");let content = REPO_REGEX.replace_all(&content, "../repo");trim_lines(&content)}diff --git a/tests/integration_tests/shell_wrapper.rs b/tests/integration_tests/shell_wrapper.rsindex f34736bd3..8ce7e8d14 100644--- a/tests/integration_tests/shell_wrapper.rs+++ b/tests/integration_tests/shell_wrapper.rs@@ -1315,6 +1315,52 @@ approved-commands = ["echo 'test command executed'"]assert_snapshot!(output.normalized());}+ #[test]+ fn test_readme_example_switch_back() {+ let mut repo = TestRepo::new();+ repo.commit("Initial commit");+ repo.setup_remote("main");++ // Create worktrees (fix-auth is where we are after step 2, feature-api exists from earlier)+ exec_through_wrapper("bash", &repo, "switch", &["--create", "fix-auth"]);+ // Create feature-api from main (simulating it already existed)+ exec_through_wrapper("bash", &repo, "switch", &["--create", "feature-api"]);++ // Switch to feature-api from fix-auth (showing navigation between worktrees)+ let fix_auth_path = repo.root_path().parent().unwrap().join("repo.fix-auth");+ let output =+ exec_through_wrapper_from("bash", &repo, "switch", &["feature-api"], &fix_auth_path);++ assert!(+ !output.combined.contains("To enable automatic cd"),+ "Shell integration hint should be suppressed"+ );++ assert_snapshot!(output.normalized());+ }++ #[test]+ fn test_readme_example_remove() {+ let mut repo = TestRepo::new();+ repo.commit("Initial commit");+ repo.setup_remote("main");++ // Create worktrees+ exec_through_wrapper("bash", &repo, "switch", &["--create", "fix-auth"]);+ exec_through_wrapper("bash", &repo, "switch", &["--create", "feature-api"]);++ // Remove feature-api from within it (current worktree removal)+ let feature_api_path = repo.root_path().parent().unwrap().join("repo.feature-api");+ let output = exec_through_wrapper_from("bash", &repo, "remove", &[], &feature_api_path);++ assert!(+ !output.combined.contains("To enable automatic cd"),+ "Shell integration hint should be suppressed"+ );++ assert_snapshot!(output.normalized());+ }+#[test]fn test_wrapper_preserves_progress_messages() {let repo = TestRepo::new();diff --git a/tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_remove.snap b/tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_remove.snapnew file mode 100644index 000000000..12beee43f--- /dev/null+++ b/tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_remove.snap@@ -0,0 +1,6 @@+---+source: tests/integration_tests/shell_wrapper.rs+assertion_line: 1362+expression: output.normalized()+---+🔄 [36m[36mRemoving [1mfeature-api[22m worktree & branch in background[39m[39mdiff --git a/tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_switch_back.snap b/tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_switch_back.snapnew file mode 100644index 000000000..9d1d0ded2--- /dev/null+++ b/tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_switch_back.snap@@ -0,0 +1,6 @@+---+source: tests/integration_tests/shell_wrapper.rs+assertion_line: 1339+expression: output.normalized()+---+✅ [32m[32mSwitched to worktree for [1mfeature-api[22m at [1m[TMPDIR]/repo.feature-api[39m[22m[39mdiff --git a/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap b/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snapindex 4dec28c78..748a9044d 100644--- a/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap+++ b/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap@@ -23,9 +23,9 @@ exit_code: 0----- stdout ---------- stderr ------ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mPath[0m [1mRemote⇅[0m [1mCommit[0m [1mAge[0m [1mMessage[0m-@ [1mmain[0m [2m^[22m[2m∥[22m [1m./repo[0m [2m∥[0m [2mb834638e[0m [2m1d[0m [2mInitial commit[0m-+ feature-x [36m+[39m [2m↑[22m [32m+5[0m [32m↑3[0m ./repo.feature-x [2m6bba16d6[0m [2m1h[0m [2mAdd file 3[0m-+ bugfix-y [2m↑[22m [32m↑1[0m ./repo.bugfix-y [2mbafa4cbd[0m [2m2h[0m [2mFix bug[0m+ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mPath[0m [1mRemote⇅[0m [1mCommit[0m [1mAge[0m [1mMessage[0m+@ [1mfeature-api[0m [36m+[39m [2m↑[22m [32m+3[0m [32m↑4[0m [1m./repo.feature-api[0m [2m5b01afca[0m [2m30m[0m [2mAdd API tests[0m+^ main [2m^[22m[2m∥[22m ./repo [2m∥[0m [2mb834638e[0m [2m1d[0m [2mInitial commit[0m++ [2mfix-auth[0m [2m_[22m [2m./repo.fix-auth[0m [2mb834638e[0m [2m1d[0m [2mInitial commit[0m-⚪ [2mShowing 3 worktrees, 1 with changes, 2 ahead[0m+⚪ [2mShowing 3 worktrees, 1 with changes, 1 ahead[0m