Skip to content

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.md
index 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 install
On 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 main
For 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.md
index 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 skill
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 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 re
Any 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.md
index 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-branch
Errors 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 test
Shell 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.md
index 9be94acbd..3aa2e4903 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -62,7 +62,7 @@ $ wt merge
Stages and commits with LLM-generated message:
```bash
-$ wt step commit
+wt step commit
```
### wt step squash
@@ -70,7 +70,7 @@ $ wt step commit
Squashes 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.md
index 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`, so
The 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://wo
Set status manually for any workflow:
```bash
-$ wt config state marker set &quot;🚧&quot; # Current branch
-$ wt config state marker set &quot;✅&quot; --branch feature # Specific branch
-$ git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;💬&quot;,&quot;set_at&quot;:0}' # Direct
+wt config state marker set &quot;🚧&quot; # Current branch
+wt config state marker set &quot;✅&quot; --branch feature # Specific branch
+git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;💬&quot;,&quot;set_at&quot;: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`](http
Worktrunk 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 worktree
Branch 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 &quot;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.'&quot;
+tmux new-session -d -s fix-auth-bug &quot;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.'&quot;
```
**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 &quot;$(wt config state logs get --hook=user:post-start:server)&quot;
+tail -f &quot;$(wt config state logs get --hook=user:post-start:server)&quot;
```
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:bui
Create an alias for frequent use:
```bash
-$ alias wtlog='f() { tail -f &quot;$(wt config state logs get --hook=&quot;$1&quot;)&quot;; }; f'
+alias wtlog='f() { tail -f &quot;$(wt config state logs get --hook=&quot;$1&quot;)&quot;; }; f'
```
## Bare repository layout
@@ -386,8 +386,8 @@ A [bare repository](https://git-scm.com/docs/gitrepository-layout) has no workin
Cloning 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.md
index 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 install
On 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 main
For 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.rs
index 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 content
let content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN
.replace_all(&content, |caps: &regex::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 frontmatter
let 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: &regex::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 $ lines
let 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: &regex::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: &regex::Captures| {
+ cmd_to_bash_block(caps.get(1).map_or("", |m| m.as_str()), "", false)
});
// Strip rawcode shortcodes (keep content)