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.mdindex 0b98b6262..f2fee90e4 100644--- a/README.md+++ b/README.md@@ -10,30 +10,27 @@<!-- [](https://crates.io/crates/worktrunk) --><!-- [](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 agentgets a separate directory. But creating worktrees, tracking paths, and cleaningup 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 listBranch Status HEAD± main↕ Path@@ -65,38 +64,6 @@ cargo install worktrunkwt 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. TheStandard `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 errorsIf 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.rsindex 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.snapnew file mode 100644index 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 -----+[1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mPath[0m [1mRemote⇅[0m [1mCommit[0m [1mAge[0m [1mMessage[0m+[1m[35mmain[0m [1m[35m./test-repo[0m [32m↑0[0m [2m[31m↓0[0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+bugfix-y ↑ [32m↑1[0m ./bugfix-y [2m412a27c8[0m [2m10 months ago[0m [2mFix bug[0m+feature-x ↑+ [32m+5[0m [32m↑3[0m ./feature-x [2m7fd821aa[0m [2m10 months ago[0m [2mAdd file 3[0m++⚪ [2mShowing 3 worktrees, 1 with changes, 2 ahead[0m++----- stderr -----