Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Fix formatting in installation commands in README (#2187)
Mahmoud Mabrok Fouadb8117b6401d9
diff --git a/README.md b/README.mdindex bed697776..4041ac70e 100644--- a/README.md+++ b/README.md@@ -107,7 +107,7 @@ A demo with some advanced features:**Homebrew (macOS & Linux):**```bash-$ brew install worktrunk && wt config shell install+brew install worktrunk && wt config shell install```Shell integration allows commands to change directories.@@ -115,7 +115,7 @@ Shell integration allows commands to change directories.**Cargo:**```bash-$ cargo install worktrunk && wt config shell install+cargo install worktrunk && wt config shell install```<details>@@ -124,8 +124,8 @@ $ cargo install worktrunk && wt config shell installOn Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:```bash-$ winget install max-sixty.worktrunk-$ git-wt config shell install+winget install max-sixty.worktrunk+git-wt config shell install```Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.@@ -135,7 +135,7 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & security**Arch Linux:**```bash-$ sudo pacman -S worktrunk && wt config shell install+sudo pacman -S worktrunk && wt config shell install```## Quick start@@ -167,9 +167,9 @@ When done, either:**PR workflow** — commit, push, open a PR, merge via GitHub/GitLab, then clean up:```bash-$ wt step commit # commit staged changes-$ gh pr create # or glab mr create-$ wt remove # after PR is merged+wt step commit # commit staged changes+gh pr create # or glab mr create+wt remove # after PR is merged```**Local merge** — squash, rebase onto main, fast-forward merge, clean up:@@ -193,9 +193,9 @@ $ wt merge mainFor parallel agents, create multiple worktrees and launch an agent in each:```bash-$ wt switch -x claude -c feature-a -- 'Add user authentication'-$ wt switch -x claude -c feature-b -- 'Fix the pagination bug'-$ wt switch -x claude -c feature-c -- 'Write tests for the API'+wt switch -x claude -c feature-a -- 'Add user authentication'+wt switch -x claude -c feature-b -- 'Fix the pagination bug'+wt switch -x claude -c feature-c -- 'Write tests for the API'```The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/#pre-start-vs-post-start) to automate setup (install deps, start dev servers).diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex 1017ee88d..515ee11b1 100644--- a/skills/worktrunk/reference/claude-code.md+++ b/skills/worktrunk/reference/claude-code.md@@ -11,14 +11,14 @@ The worktrunk Claude Code plugin provides three features:Recommended:```bash-$ wt config plugins claude install+wt config plugins claude install```Manual equivalent:```bash-$ claude plugin marketplace add max-sixty/worktrunk-$ claude plugin install worktrunk@worktrunk+claude plugin marketplace add max-sixty/worktrunk+claude plugin install worktrunk@worktrunk```## Configuration skilldiff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex f6fce7b1b..520f89564 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -107,9 +107,9 @@ open = "open http://localhost:{{ branch | hash_port }}"``````bash-$ wt step deploy-$ wt step deploy --dry-run-$ wt step deploy --env=staging+wt step deploy+wt step deploy --dry-run+wt step deploy --env=staging```An `up` alias that fetches all remotes and rebases each worktree onto its upstream:@@ -187,8 +187,8 @@ See [`wt step` — Aliases](https://worktrunk.dev/step/#aliases) for the full reAny executable named `wt-<name>` on `PATH` becomes available as `wt <name>` — the same pattern git uses for `git-foo`. Built-in commands always take precedence.```bash-$ wt sync origin # runs: wt-sync origin-$ wt -C /tmp/repo sync # -C is forwarded as the child's working directory+wt sync origin # runs: wt-sync origin+wt -C /tmp/repo sync # -C is forwarded as the child's working directory```Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. External subcommands don't have access to template variables.diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex 9b4ee5549..128426901 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -136,7 +136,7 @@ Worktrunk can delete **worktrees** and **branches**. Both have safeguards.For worktrees containing precious ignored data (databases, caches, large assets), use `git worktree lock`:```bash-$ git worktree lock ../myproject.feature --reason "Contains local database"+git worktree lock ../myproject.feature --reason "Contains local database"```Locked worktrees show `⊞` in `wt list`. Neither `git worktree remove` nor `wt remove` (even with `--force`) will delete them. Unlock with `git worktree unlock`.@@ -220,7 +220,7 @@ For full details on the detection mechanism, see `wt config state default-branchErrors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:```bash-$ cargo install worktrunk --no-default-features+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.@@ -230,7 +230,7 @@ This disables bash syntax highlighting in command output but keeps all core func### Quick tests```bash-$ cargo test+cargo test```### Full integration tests@@ -238,7 +238,7 @@ $ cargo testShell integration tests require bash, zsh, fish, and nushell:```bash-$ cargo test --test integration --features shell-integration-tests+cargo test --test integration --features shell-integration-tests```## How can I contribute?diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.mdindex 9be94acbd..3aa2e4903 100644--- a/skills/worktrunk/reference/llm-commits.md+++ b/skills/worktrunk/reference/llm-commits.md@@ -62,7 +62,7 @@ $ wt mergeStages and commits with LLM-generated message:```bash-$ wt step commit+wt step commit```### wt step squash@@ -70,7 +70,7 @@ $ wt step commitSquashes branch commits into one with LLM-generated message:```bash-$ wt step squash+wt step squash```See [`wt merge`](https://worktrunk.dev/merge/) and [`wt step`](https://worktrunk.dev/step/) for full documentation.diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex 2fda5fc98..3b7a58ab7 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -7,9 +7,9 @@ Practical recipes for common Worktrunk workflows.Create a worktree and launch Claude in one command:```bash-$ alias wsc='wt switch --create --execute=claude'-$ wsc new-feature # Creates worktree, runs hooks, launches Claude-$ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`+alias wsc='wt switch --create --execute=claude'+wsc new-feature # Creates worktree, runs hooks, launches Claude+wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'````## `wt` aliases@@ -103,7 +103,7 @@ The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, soThe connection string is accessible anywhere — not just in hooks:```bash-$ DATABASE_URL=$(wt config state vars get db_url) npm start+DATABASE_URL=$(wt config state vars get db_url) npm start```## Eliminate cold starts@@ -170,9 +170,9 @@ Custom emoji markers show agent state in `wt list`. The [Claude Code](https://woSet status manually for any workflow:```bash-$ wt config state marker set "🚧" # Current branch-$ wt config state marker set "✅" --branch feature # Specific branch-$ git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct+wt config state marker set "🚧" # Current branch+wt config state marker set "✅" --branch feature # Specific branch+git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct```See [Claude Code Integration](https://worktrunk.dev/claude-code/#installation) for plugin installation.@@ -180,7 +180,7 @@ See [Claude Code Integration](https://worktrunk.dev/claude-code/#installation) f## Monitor CI across branches```bash-$ wt list --full --branches+wt list --full --branches```Shows PR/CI status for all branches, including those without worktrees. CI indicators are clickable links to the PR page.@@ -200,7 +200,7 @@ Summaries are cached and regenerated only when the diff changes. See [LLM Commit## JSON API```bash-$ wt list --format=json+wt list --format=json```Structured output for dashboards, statuslines, and scripts. See [`wt list`](https://worktrunk.dev/list/) for query examples.@@ -210,7 +210,7 @@ Structured output for dashboards, statuslines, and scripts. See [`wt list`](httpWorktrunk maintains useful state. Default branch [detection](https://worktrunk.dev/config/#wt-config-state-default-branch), for instance, means scripts work on any repo — no need to hardcode `main` or `master`:```bash-$ git rebase $(wt config state default-branch)+git rebase $(wt config state default-branch)```## Task runners in hooks@@ -230,9 +230,9 @@ Reference Taskfile/Justfile/Makefile in hooks:Special arguments work across all commands—see [`wt switch`](https://worktrunk.dev/switch/#shortcuts) for the full list.```bash-$ wt switch --create hotfix --base=@ # Branch from current HEAD-$ wt switch - # Switch to previous worktree-$ wt remove @ # Remove current worktree+wt switch --create hotfix --base=@ # Branch from current HEAD+wt switch - # Switch to previous worktree+wt remove @ # Remove current worktree```## Stacked branches@@ -240,7 +240,7 @@ $ wt remove @ # Remove current worktreeBranch from current HEAD instead of the default branch:```bash-$ wt switch --create feature-part2 --base=@+wt switch --create feature-part2 --base=@```Creates a worktree that builds on the current branch's changes.@@ -251,14 +251,14 @@ Spawn a worktree with an agent CLI running in the background. Examples below use**tmux** (new detached session):```bash-$ tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \-$ 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"+tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \+ 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"```**Zellij** (new pane in current session):```bash-$ zellij run -- wt switch --create fix-auth-bug -x claude -- \-$ 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'+zellij run -- wt switch --create fix-auth-bug -x claude -- \+ 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'```This lets one agent session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane.@@ -368,7 +368,7 @@ url = "http://{{ branch | sanitize }}.{{ repo }}.localhost:8080"Follow background hook output in real-time:```bash-$ tail -f "$(wt config state logs get --hook=user:post-start:server)"+tail -f "$(wt config state logs get --hook=user:post-start:server)"```The `--hook` format is `source:hook-type:name` — e.g., `project:post-start:build` for project-defined hooks. Use `wt config state logs get` to list all available logs.@@ -376,7 +376,7 @@ The `--hook` format is `source:hook-type:name` — e.g., `project:post-start:buiCreate an alias for frequent use:```bash-$ alias wtlog='f() { tail -f "$(wt config state logs get --hook="$1")"; }; f'+alias wtlog='f() { tail -f "$(wt config state logs get --hook="$1")"; }; f'```## Bare repository layout@@ -386,8 +386,8 @@ A [bare repository](https://git-scm.com/docs/gitrepository-layout) has no workinCloning a bare repo into `<project>/.git` puts all worktrees under one directory:```bash-$ git clone --bare <url> myproject/.git-$ cd myproject+git clone --bare <url> myproject/.git+cd myproject```With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:@@ -410,7 +410,7 @@ worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"Create the first worktree:```bash-$ wt switch --create main+wt switch --create main```Now `wt switch --create feature` creates `myproject/feature/`.diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.mdindex 45f30f941..b0d4d0077 100644--- a/skills/worktrunk/reference/worktrunk.md+++ b/skills/worktrunk/reference/worktrunk.md@@ -86,7 +86,7 @@ A demo with some advanced features:**Homebrew (macOS & Linux):**```bash-$ brew install worktrunk && wt config shell install+brew install worktrunk && wt config shell install```Shell integration allows commands to change directories.@@ -94,7 +94,7 @@ Shell integration allows commands to change directories.**Cargo:**```bash-$ cargo install worktrunk && wt config shell install+cargo install worktrunk && wt config shell install```<details>@@ -103,8 +103,8 @@ $ cargo install worktrunk && wt config shell installOn Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:```bash-$ winget install max-sixty.worktrunk-$ git-wt config shell install+winget install max-sixty.worktrunk+git-wt config shell install```Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.@@ -114,7 +114,7 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & security**Arch Linux:**```bash-$ sudo pacman -S worktrunk && wt config shell install+sudo pacman -S worktrunk && wt config shell install```## Quick start@@ -144,9 +144,9 @@ When done, either:**PR workflow** — commit, push, open a PR, merge via GitHub/GitLab, then clean up:```bash-$ wt step commit # commit staged changes-$ gh pr create # or glab mr create-$ wt remove # after PR is merged+wt step commit # commit staged changes+gh pr create # or glab mr create+wt remove # after PR is merged```**Local merge** — squash, rebase onto main, fast-forward merge, clean up:@@ -169,9 +169,9 @@ $ wt merge mainFor parallel agents, create multiple worktrees and launch an agent in each:```bash-$ wt switch -x claude -c feature-a -- 'Add user authentication'-$ wt switch -x claude -c feature-b -- 'Fix the pagination bug'-$ wt switch -x claude -c feature-c -- 'Write tests for the API'+wt switch -x claude -c feature-a -- 'Add user authentication'+wt switch -x claude -c feature-b -- 'Fix the pagination bug'+wt switch -x claude -c feature-c -- 'Write tests for the API'```The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/#pre-start-vs-post-start) to automate setup (install deps, start dev servers).diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex b09ade1bb..3001a26ca 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -917,7 +917,7 @@ fn transform_zola_to_github(content: &str) -> String {// These are `{{ terminal(cmd="...") }}` shortcodes without body contentlet content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN.replace_all(&content, |caps: ®ex::Captures| {- cmd_to_bash_block(caps.get(1).map_or("", |m| m.as_str()), "")+ cmd_to_bash_block(caps.get(1).map_or("", |m| m.as_str()), "", false)}).into_owned();@@ -1895,8 +1895,11 @@ static SPAN_CMD_TO_DOLLAR: LazyLock<Regex> =LazyLock::new(|| Regex::new(r#"<span class="cmd">([^<]*)</span>"#).unwrap());/// Convert a `|||`-delimited cmd string (and optional body) into a ```bash block.-/// Each cmd line gets `$ ` prefix; comment lines (`#`) and blank lines pass through.-fn cmd_to_bash_block(cmd: &str, body: &str) -> String {+/// When `with_prompt` is false, command lines pass through verbatim so the block+/// is directly copy-pasteable. When true, command lines get a `$ ` prefix to+/// distinguish them from interleaved output. Comment-only lines (`#`) and blank+/// lines never get the prefix.+fn cmd_to_bash_block(cmd: &str, body: &str, with_prompt: bool) -> String {let mut result = String::from("```bash\n");for line in cmd.split("|||") {if line.is_empty() {@@ -1905,7 +1908,9 @@ fn cmd_to_bash_block(cmd: &str, body: &str) -> String {result.push_str(line);result.push('\n');} else {- result.push_str("$ ");+ if with_prompt {+ result.push_str("$ ");+ }result.push_str(line);result.push('\n');}@@ -1944,12 +1949,15 @@ fn transform_docs_for_skill(content: &str) -> String {// Strip frontmatterlet content = ZOLA_FRONTMATTER_PATTERN.replace(content, "");- // Strip terminal shortcodes, converting cmd parameters back to `$ command` blocks.- // Commands joined by `|||` are split into separate lines.+ // Strip terminal shortcodes, converting cmd parameters back to bash blocks.+ // Commands joined by `|||` are split into separate lines. Block-form shortcodes+ // with a body interleave command + output, so we keep the `$ ` prompt prefix+ // there to distinguish the two; self-closing shortcodes are pure commands and+ // get no prefix so the block stays copy-pasteable.let content = ZOLA_TERMINAL_BODY_PATTERN.replace_all(&content, |caps: ®ex::Captures| {let body = caps.get(2).map_or("", |m| m.as_str());match caps.get(1) {- Some(cmd) => cmd_to_bash_block(cmd.as_str(), body),+ Some(cmd) => cmd_to_bash_block(cmd.as_str(), body, !body.trim().is_empty()),None if body.contains(r#"<span class="cmd">"#) => {// Old-style body shortcode with <span class="cmd"> — convert to $ lineslet converted = SPAN_CMD_TO_DOLLAR.replace_all(body, "$$ $1");@@ -1960,9 +1968,9 @@ fn transform_docs_for_skill(content: &str) -> String {None => strip_html(body),}});- let content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN- .replace_all(&content, |caps: ®ex::Captures| {- cmd_to_bash_block(caps.get(1).map_or("", |m| m.as_str()), "")+ let content =+ ZOLA_TERMINAL_SELF_CLOSING_PATTERN.replace_all(&content, |caps: ®ex::Captures| {+ cmd_to_bash_block(caps.get(1).map_or("", |m| m.as_str()), "", false)});// Strip rawcode shortcodes (keep content)