Skip to content

docs: writing-prose cleanup (faq, config, list, remove) - #2925

Merged
max-sixty merged 2 commits into
mainfrom
doc-improve
May 27, 2026
Merged

max-sixty merged 2 commits into
mainfrom
doc-improve

Conversation

@max-sixty

Copy link
Copy Markdown
Owner

Continues the writing-prose pass on the remaining doc-site pages — the items deferred at the end of #2922.

faq.md — dropped "Worktrunk creates files in four categories." scaffolding; the four H3s below (Worktree directories, Config files, Shell integration, Metadata in .git) make the count self-evident.

config.md (edits in the Config command's after_long_help in src/cli/mod.rs) — four small fixes:

  • Replaced the "For context:" three-bullet preamble in User project-specific settings with a direct lead sentence. Side benefit: fixes the "User configs also has" grammar bug. The new sentence avoids second-person ("for you") and third-person addressing ("for the user") per the writing-prose indicative-mood rule.
  • Dropped "also" from the system-config sentence — it was the only signal the sentence was an orphan footnote relative to the table above.
  • Dropped "Similarly," before the first-commit-prompt sentence; the parallel "On first run … On first commit …" structure carries the relation.
  • Dropped "Note the single underscore after WORKTRUNK and double underscores between nested keys." that restated what the env-var table already showed.

list.md (edits in the List command's after_long_help) — folded the three-dot diff detail into the main…± column description; tightened the remaining footnote to just the label-stays-main point.

remove.md (edits in the Remove command's after_long_help) — extracted the cap-detail appendix from the "Patch-id match" bullet, which had four sentences while the surrounding five bullets averaged one or two; it now sits as its own paragraph. Also dropped the two sentences in Force flags that inverted the force-flags table just above; only the new --no-delete-branch note remains.

Skipped (re-reviewed and judged not worth changing):

  • switch.md fork material — mechanism + naming-rule, not duplication.
  • step.md mixed-shape operations list — the asymmetry signals which subcommands have subdoc sections.
  • step.md "How it works" subsections — useful reference content, not internal commentary.
  • step.md wt step promote opener — opinionated voice framing.
  • step.md wt step tether "Why" — now the canonical place for the leakage rationale (the tips-patterns dup was already removed in docs: writing-prose cleanup (claude-code, hook, llm-commits, tips-patterns) #2922).

Auto-synced skill mirrors (skills/worktrunk/reference/) and regenerated help snapshots carry the same edits.

faq.md: drop "Worktrunk creates files in four categories" scaffolding
(the four H3s make it self-evident).

config.md (via Config command's after_long_help): replace the "For
context:" three-bullet preamble in user-project-specific-settings with
a direct lead sentence (also fixes the "User configs _also_ has"
grammar bug); drop "also" from the system-config sentence; drop
"Similarly," before the first-commit-prompt sentence (parallel
structure conveys the relation); drop "Note the single underscore..."
that restated the env-var table.

list.md (via List command's after_long_help): fold the three-dot diff
detail into the `main…±` column description; tighten the remaining
note to just the label-stays-main point.

remove.md (via Remove command's after_long_help): extract the
cap-detail appendix from bullet #6 (broke parallel with the other
five); drop the two sentences that inverted the force-flags table.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The snapshot wasn't regenerated to match the new dev/config.example.toml wording — the snap line says "table that holds project-specific settings for the user" but every other source file (the TOML, docs/content/config.md, skills/worktrunk/reference/config.md, src/cli/mod.rs) now says "table for project-specific settings". cargo insta test --accept -- --test integration "help_config" should clear it; per tests/CLAUDE.md, hand-editing the snap isn't recommended because of the ANSI escapes.

The earlier insta run captured help_config_long but not
help_config_create, which embeds the same `[projects]` after_long_help
fragment.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@max-sixty
max-sixty merged commit 2617348 into main May 27, 2026
36 checks passed
@max-sixty
max-sixty deleted the doc-improve branch May 27, 2026 09:18
@max-sixty max-sixty mentioned this pull request May 30, 2026
max-sixty added a commit that referenced this pull request May 30, 2026
v0.55.0.

`cargo semver-checks` reports breaking library API changes (9 inherent methods removed from `Repository` / `ShellConfig` by the dead-code cut-overs in #2931 — `is_ancestor`, `same_commit`, `has_added_changes`, `trees_match`, `head_tree_matches_branch`, `has_merge_conflicts`, `has_merge_conflicts_by_tree`, `merge_integration_probe`, `is_posix`). None are intentional public API, but they force a minor bump pre-1.0.

Headline user-visible changes:
- `wt switch` accepts forge PR/MR URLs anywhere `pr:N` / `mr:N` works (#2898, thanks @thiagowfx for the request).
- Claude Code plugin keeps unmerged branches during worktree cleanup — the `WorktreeRemove` hook drops `-D` (#2940, thanks @jbeda for reporting).
- `wt list` and `wt step prune` degrade gracefully on unborn worktrees (#2937, thanks @nedtwigg for reporting).
- `-vv` startup pointer now names `diagnostic.md` (#2919).
- Doc-site and `--help` prose cleanup (#2922, #2925); internal cut-over of duplicated/dead code paths (#2931, #2932, #2934).

Full CHANGELOG entry in this PR.

> _This was written by Claude Code on behalf of max_
social4hyq pushed a commit to social4hyq/homebrew-core that referenced this pull request Sep 20, 2026
worktrunk 0.55.0

Created-by: HarmonybrewBot
Commit-by: HarmonybrewBot
Merged-by: HarmonybrewBot
Description: Created by `brew bump`

---

Created with `brew bump-formula-pr`.<details>
  <summary>release notes</summary>
  <pre>## Release Notes

### Improved

- **`wt switch` accepts forge PR/MR URLs**: `wt switch https://github.com/owner/repo/pull/123` now resolves the same way as `wt switch pr:123`, and the URL form works anywhere a `pr:N` / `mr:N` shortcut does (positional argument and `--base`). Detection is shape-based, not host-based — any `http(s)://` URL whose path contains `/pull/N`, `/pulls/N`, `/-/merge_requests/N`, or `/pullrequest/N` matches, covering GitHub (including Enterprise), GitLab, Gitea, and Azure DevOps, including self-hosted instances. ([#2898](max-sixty/worktrunk#2898), thanks @thiagowfx for the request)

- **`-vv` startup pointer names `diagnostic.md`**: The `-vv` pointer now lists the shared log directory once with all three files it will contain — `trace.log`, `subprocess.log`, and `diagnostic.md` — so the diagnostic bundle is discoverable at startup rather than only when the gist hint fires at exit. The pointer verb reads `Writing to …` instead of `Tracing to …`. ([#2919](max-sixty/worktrunk#2919))

### Fixed

- **Claude Code plugin keeps unmerged branches during worktree cleanup**: The plugin's `WorktreeRemove` hook passed `-D` (`--force-delete`) to `wt remove`, which removes a branch even when it carries commits that aren't merged or pushed. The hook now uses the default removal: a merged or integrated branch is removed cleanly, while one with unmerged commits is kept, with a `wt remove -D <branch>` hint for deleting it deliberately. ([#2940](max-sixty/worktrunk#2940), thanks @jbeda for reporting)

- **`wt list` and `wt step prune` degrade gracefully on unborn worktrees**: A linked worktree created with `git worktree add --orphan` sits on an unborn branch whose `HEAD` is the null OID. `wt list` used to show `working-tree-diff (fatal: ambiguous argument 'HEAD')` and a merge-tree error in its columns, and `wt step prune` aborted its entire scan with `fatal: Needed a single revision`, blocking pruning of every other worktree. Both now treat an unborn worktree as having no commits: `wt list` renders `·` for the commit-dependent columns, and `wt step prune` skips it (as it does locked worktrees) and continues. ([#2937](max-sixty/worktrunk#2937), thanks @nedtwigg for reporting)

### Documentation

- **Doc-site and `--help` prose cleanup**: A writing-prose pass across the FAQ, config, list, remove, Claude Code, hook, LLM-commits, and Tips & Patterns pages (some via `--help` text in `after_long_help`). ([#2922](max-sixty/worktrunk#2922), [#2925](max-sixty/worktrunk#2925))

### Internal

- **Collapsed duplicated code paths and removed dead code left by completed cut-overs**: A net reduction across the shell, git, and command layers. ([#2931](max-sixty/worktrunk#2931), [#2932](max-sixty/worktrunk#2932), [#2934](max-sixty/worktrunk#2934))

## Install worktrunk 0.55.0

### Install prebuilt binaries via shell script

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-installer.sh | sh && wt config shell install
```

### Install prebuilt binaries via powershell script

```sh
powershell -ExecutionPolicy Bypass -c "irm https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-installer.ps1 | iex"; git-wt config shell install
```

### Install prebuilt binaries via Homebrew

```sh
brew install worktrunk && wt config shell install
```

## Download worktrunk 0.55.0

|  File  | Platform | Checksum |
|--------|----------|----------|
| [worktrunk-aarch64-apple-darwin.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-aarch64-apple-darwin.tar.xz) | Apple Silicon macOS | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-aarch64-apple-darwin.tar.xz.sha256) |
| [worktrunk-x86_64-apple-darwin.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-x86_64-apple-darwin.tar.xz) | Intel macOS | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-x86_64-apple-darwin.tar.xz.sha256) |
| [worktrunk-x86_64-pc-windows-msvc.zip](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-x86_64-pc-windows-msvc.zip) | x64 Windows | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-x86_64-pc-windows-msvc.zip.sha256) |
| [worktrunk-aarch64-unknown-linux-musl.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-aarch64-unknown-linux-musl.tar.xz) | ARM64 MUSL Linux | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-aarch64-unknown-linux-musl.tar.xz.sha256) |
| [worktrunk-x86_64-unknown-linux-musl.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-x86_64-unknown-linux-musl.tar.xz) | x64 MUSL Linux | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.55.0/worktrunk-x86_64-unknown-linux-musl.tar.xz.sha256) |



### Install via Cargo

```sh
cargo install worktrunk && wt config shell install
```

### Install via Winget (Windows)

```sh
winget install max-sixty.worktrunk && git-wt config shell install
```

### Install via AUR (Arch Linux)

```sh
paru worktrunk-bin && wt config shell install
```
</pre>
  <p>View the full release notes at <a href="https://github.com/max-sixty/worktrunk/releases/tag/v0.55.0">https://github.com/max-sixty/worktrunk/releases/tag/v0.55.0</a>.</p>
</details>
<hr>

See merge request: Harmonybrew/homebrew-core!9819
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants