Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: Improve README clarity, add FAQ, and clarify command execution

Maximilian Roosa6b23cece97b
diff --git a/README.md b/README.md
index 0b98b6262..f2fee90e4 100644
--- a/README.md
+++ b/README.md
@@ -10,30 +10,27 @@
<!-- [![Downloads](https://img.shields.io/crates/d/worktrunk?style=for-the-badge&logo=rust)](https://crates.io/crates/worktrunk) -->
<!-- [![Stars](https://img.shields.io/github/stars/max-sixty/worktrunk?style=for-the-badge&logo=github)](https://github.com/max-sixty/worktrunk/stargazers) -->
-Worktrunk is a CLI tool to make working with git worktrees much much easier.
-It's designed for those running concurrent AI coding agents.
+Worktrunk is a CLI tool which makes working with git worktrees much much easier.
+It's designed for those running many concurrent AI coding agents.
-Git worktrees let multiple agents work on one repo without colliding; each agent
+Git worktrees let multiple agents work on a single repo without colliding; each agent
gets a separate directory. But creating worktrees, tracking paths, and cleaning
up afterward is manual. Worktrunk automates that lifecycle.
## Quick Start
-Worktrunk automates the full worktree lifecycle: create worktree, work, merge back, remove worktree.
-
-<!-- Output generated from:
- Switch: tests/snapshots/integration__integration_tests__merge__readme_example_simple_switch.snap
- Merge: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap
- (snapshot output includes [SHA]/[REPO]; replace with representative values when copying into README) -->
-
**Create a worktree:**
+<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_simple_switch.snap -->
+
```bash
$ wt switch --create fix-auth
✅ Created new worktree for fix-auth from main at ../repo.fix-auth/
```
-**Work on your changes, then merge back:**
+**Work, make changes, then merge back:**
+
+<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap -->
```bash
$ wt merge
@@ -50,6 +47,8 @@ $ wt merge
**See all active worktrees:**
+<!-- Output from: tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap -->
+
```bash
$ wt list
Branch Status HEAD± main↕ Path
@@ -65,38 +64,6 @@ cargo install worktrunk
wt config shell # Sets up shell integration
```
-## Tips
-
-**Create an alias for your favorite agent** - Shell aliases streamline common workflows. For example, to create a worktree and immediately start Claude:
-
-```bash
-alias wsl='wt switch --create --execute=claude'
-```
-
-Now `wsl new-feature` creates a branch, sets up the worktree, runs initialization hooks, and launches Claude in that directory.
-
-**Automatic branch status in Claude Code** - The Claude Code integration shows which branches have active AI sessions. When Claude starts working, the branch shows `🤖` in `wt list`. When waiting for input, it shows `💬`. Setup instructions: [Custom Worktree Status](#custom-worktree-status).
-
-**Auto-generated commit messages** - Simon Willison's [llm](https://llm.datasette.io/) tool integrates seamlessly with worktrunk's commit generation. Install it, configure the command, and `wt merge` will automatically generate contextual commit messages. Setup guide: [LLM-Powered Commit Messages](#llm-powered-commit-messages).
-
-**Environment setup with hooks** - Each worktree is a separate directory. Use `post-create-command` to ensure consistent environments:
-
-```toml
-# In .config/wt.toml
-[post-create-command]
-"setup" = "uv sync && nvm install"
-```
-
-**Delegate to task runners** - Reference existing Justfile/Makefile commands instead of duplicating logic:
-
-```toml
-[post-create-command]
-"setup" = "just install"
-
-[pre-merge-command]
-"validate" = "just test lint"
-```
-
## Automation Features
### LLM-Powered Commit Messages
@@ -130,7 +97,7 @@ $ wt merge
✅ Squashed @ a1b2c3d
```
-Set up LLM integration: `wt config help` shows the setup guide, `wt config init` creates example config.
+Set up LLM integration: run `wt config help` to see the setup guide, or `wt config init` to create an example config file.
<details>
<summary><b>Advanced: Custom Prompt Templates</b></summary>
@@ -331,6 +298,38 @@ Worktrunk is opinionated! It's not designed to be all things to all people. The
Standard `git worktree` commands continue working fine — adopting Worktrunk for a portion of a workflow doesn't require adopting it for everything.
+## Tips
+
+**Create an alias for your favorite agent** - Shell aliases streamline common workflows. For example, to create a worktree and immediately start Claude:
+
+```bash
+alias wsl='wt switch --create --execute=claude'
+```
+
+Now `wsl new-feature` creates a branch, sets up the worktree, runs initialization hooks, and launches Claude in that directory.
+
+**Automatic branch status in Claude Code** - The Claude Code integration shows which branches have active AI sessions. When Claude starts working, the branch shows `🤖` in `wt list`. When waiting for input, it shows `💬`. Setup instructions: [Custom Worktree Status](#custom-worktree-status).
+
+**Auto-generated commit messages** - Simon Willison's [llm](https://llm.datasette.io/) tool integrates seamlessly with worktrunk's commit generation. Install it, configure the command, and `wt merge` will automatically generate contextual commit messages. Setup guide: [LLM-Powered Commit Messages](#llm-powered-commit-messages).
+
+**Environment setup with hooks** - Each worktree is a separate directory. Use `post-create-command` to ensure consistent environments:
+
+```toml
+# In .config/wt.toml
+[post-create-command]
+"setup" = "uv sync && nvm install"
+```
+
+**Delegate to task runners** - Reference existing Justfile/Makefile commands instead of duplicating logic:
+
+```toml
+[post-create-command]
+"setup" = "just install"
+
+[pre-merge-command]
+"validate" = "just test lint"
+```
+
## All Commands
- `wt switch [branch]` - Switch to existing worktree
@@ -579,6 +578,27 @@ Run without `--execute` to preview changes first.
## FAQ
+### Does Worktrunk execute arbitrary commands on my machine?
+
+Worktrunk executes commands in three contexts:
+
+1. **Project hooks** (`.config/wt.toml`) - Automation for worktree lifecycle
+2. **LLM commands** (`~/.config/worktrunk/config.toml`) - Commit message generation
+3. **--execute flag** - Commands you provide explicitly
+
+Commands from project hooks and LLM configuration require approval on first run. Approved commands are saved to `~/.config/worktrunk/approved.toml`. If a command changes, worktrunk requires new approval.
+
+**Example approval prompt:**
+
+```
+💡 Permission required: post-create install
+ uv sync
+
+💡 Allow and remember? [y/N]
+```
+
+Use `--force` to bypass prompts (useful for CI/automation).
+
### Installation fails with C compilation errors
If you encounter errors related to tree-sitter or C compilation (like "error: 'for' loop initial declarations are only allowed in C99 mode" or "undefined reference to le16toh"), install without syntax highlighting:
diff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rs
index a2a43d606..f0c388c5f 100644
--- a/tests/integration_tests/list.rs
+++ b/tests/integration_tests/list.rs
@@ -675,3 +675,68 @@ 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.
+/// Output: tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap
+#[test]
+fn test_readme_example_simple_list() {
+ let mut repo = TestRepo::new();
+ repo.commit("Initial commit");
+ repo.setup_remote("main");
+
+ // Create worktrees with various states
+ let feature_x = repo.add_worktree("feature-x", "feature-x");
+ let bugfix_y = repo.add_worktree("bugfix-y", "bugfix-y");
+
+ // feature-x: ahead with uncommitted changes
+ // Make 3 commits
+ for i in 1..=3 {
+ std::fs::write(
+ feature_x.join(format!("file{}.txt", i)),
+ format!("content {}", i),
+ )
+ .expect("Failed to write file");
+ let mut cmd = Command::new("git");
+ repo.configure_git_cmd(&mut cmd);
+ cmd.args(["add", &format!("file{}.txt", i)])
+ .current_dir(&feature_x)
+ .output()
+ .expect("Failed to add");
+ let mut cmd = Command::new("git");
+ repo.configure_git_cmd(&mut cmd);
+ cmd.args(["commit", "-m", &format!("Add file {}", i)])
+ .current_dir(&feature_x)
+ .output()
+ .expect("Failed to commit");
+ }
+ // Add unstaged changes (+5 -2 lines)
+ std::fs::write(
+ feature_x.join("modified.txt"),
+ "line1\nline2\nline3\nline4\nline5\n",
+ )
+ .expect("Failed to write");
+ let mut cmd = Command::new("git");
+ repo.configure_git_cmd(&mut cmd);
+ cmd.args(["add", "modified.txt"])
+ .current_dir(&feature_x)
+ .output()
+ .expect("Failed to add");
+
+ // bugfix-y: 1 commit ahead, clean tree
+ std::fs::write(bugfix_y.join("bugfix.txt"), "fix content").expect("Failed to write file");
+ let mut cmd = Command::new("git");
+ repo.configure_git_cmd(&mut cmd);
+ cmd.args(["add", "bugfix.txt"])
+ .current_dir(&bugfix_y)
+ .output()
+ .expect("Failed to add");
+ let mut cmd = Command::new("git");
+ repo.configure_git_cmd(&mut cmd);
+ cmd.args(["commit", "-m", "Fix bug"])
+ .current_dir(&bugfix_y)
+ .output()
+ .expect("Failed to commit");
+
+ snapshot_list("readme_example_simple_list", &repo);
+}
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
new file mode 100644
index 000000000..8480c2fb0
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap
@@ -0,0 +1,30 @@
+---
+source: tests/integration_tests/list.rs
+info:
+ program: wt
+ args:
+ - list
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: /dev/null
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ LANG: C
+ LC_ALL: C
+ SOURCE_DATE_EPOCH: "1761609600"
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpppVUpK/test-config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
+main ./test-repo ↑0 ↓0 b834638e 10 months ago Initial commit
+bugfix-y ↑ ↑1 ./bugfix-y 412a27c8 10 months ago Fix bug
+feature-x ↑+ +5 ↑3 ./feature-x 7fd821aa 10 months ago Add file 3
+
+⚪ Showing 3 worktrees, 1 with changes, 2 ahead
+
+----- stderr -----