Skip to content

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.md
index 3043e5f55..a80287d94 100644
--- a/README.md
+++ b/README.md
@@ -57,43 +57,50 @@ $ wt switch --create fix-auth
This 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 lifecycle
cd ../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.feature
git 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 messages
diff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rs
index 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.rs
index 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 placeholder
static 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.rs
index 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.snap
new file mode 100644
index 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()
+---
+🔄 Removing feature-api worktree & branch in background
diff --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.snap
new file mode 100644
index 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()
+---
+✅ Switched to worktree for feature-api at [TMPDIR]/repo.feature-api
diff --git a/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap b/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap
index 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 -----
- 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