From bbd3f51340f8c22f9cfa6c96571ace092067f253 Mon Sep 17 00:00:00 2001 From: Evgeniy Podivilov Date: Sat, 20 Jun 2026 21:39:39 +0100 Subject: [PATCH 1/2] docs(readme): document missing commands and features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for several existing but undocumented surfaces: - wt self-update: in-place binary update with supported platforms - wt list --json: JSON output shape for scripting and AI agents - wt list drift badge: explain "dir≠branch" indicator - wt update --cleanup: combined fetch + rebase + drop gone branches - post-sync hook: ran after wt sync applies config changes Closes Vikunja #41 (id 213) --- README.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 05ec0c7..5771a1a 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,16 @@ wt list |------|-------------| | `--json` | Output as JSON array | -Output shows each worktree with its path. Badges: `(main)` for the main worktree, `(current)` for the active one. +Output shows each worktree with its path. Badges: `(main)` for the main worktree, `(current)` for the active one, `⚠ dir≠branch` when the worktree directory name does not match its branch name (drift — usually a leftover from a branch rename or a directory moved by hand). The drift badge only appears when a config defines `rootDir` and the worktree lives under it. + +**JSON output** — `--json` writes a single-line JSON array to stdout (no intro/outro), suitable for scripting and AI agents: + +```json +[ + { "branch": "main", "path": "/repo", "isMain": true, "isCurrent": false, "drifted": false }, + { "branch": "feature/x", "path": "/worktrees/feature/x", "isMain": false, "isCurrent": true, "drifted": false } +] +``` ### `wt remove` @@ -225,6 +234,7 @@ wt update [branch] [options] | Flag | Description | |------|-------------| | `--dry-run` | Show what would be done without making changes | +| `--cleanup` | Automatically clean up branches with gone remotes after update | **Examples:** @@ -237,6 +247,9 @@ wt update feature/parent # Preview what would happen wt update --dry-run + +# Fetch, rebase, and drop branches whose remote was deleted — no prompts +wt update --cleanup ``` **How it works:** @@ -278,7 +291,7 @@ After each successful rebase, `post-update` hooks are executed for that branch. } ``` -After update completes, if any worktrees have branches that were deleted on the remote, an interactive prompt offers to clean them up. +After update completes, if any worktrees have branches that were deleted on the remote, an interactive prompt offers to clean them up. Pass `--cleanup` to skip the prompt and run the cleanup automatically — convenient as a single end-of-day or CI command (`wt update --cleanup`) that combines fetch, rebase, and stale-branch removal, in place of `wt update` followed by `wt cleanup`. In non-interactive mode, `--cleanup` is required to actually drop branches; otherwise `wt update` just reports that stale branches exist. ### `wt doctor` @@ -363,6 +376,18 @@ wt config show [options] Each field shows its origin: `global`, `repo`, `local`, or `default`. The sources header lists all config file paths (or hints where to create missing ones). +### `wt self-update` + +Replace the running `wt` binary in place with the latest release from GitHub. + +```bash +wt self-update +``` + +Checks the latest release, downloads the matching prebuilt binary, and atomically replaces the current executable. Supported on Linux and macOS (x64 and arm64); on macOS the `com.apple.quarantine` attribute is stripped after install. On Windows, re-run the PowerShell installer from the [Installation](#installation) section instead. + +The binary is replaced in place at `process.execPath`, so the current user must have write access to that location. If you installed `wt` to a system directory (e.g. `/usr/local/bin`), re-run with elevated permissions; otherwise install to a user-writable directory such as `~/.local/bin`. + ## Exit codes | Code | Meaning | @@ -430,6 +455,7 @@ Create a `.worktreekit.jsonc` file in the project root (or use `wt init`). JSONC | `hooks.pre-remove` | `string[]` | `[]` | Commands to run before removing a worktree | | `hooks.post-update` | `string[]` | `[]` | Commands to run after each branch is successfully rebased | | `hooks.on-conflict` | `string[]` | `[]` | Commands to run when rebase hits a conflict. Expected to resolve and complete the rebase | +| `hooks.post-sync` | `string[]` | `[]` | Commands to run after `wt sync` applies copy/symlink changes to a worktree | ### Local Config Overrides From b045aacce72e728ebdf9eeb987f5df1531033290 Mon Sep 17 00:00:00 2001 From: Evgeniy Podivilov Date: Sat, 20 Jun 2026 21:51:37 +0100 Subject: [PATCH 2/2] docs(readme): address review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drift badge: drop the inaccurate "lives under rootDir" clause — isDrifted() fires for any worktree whose path != /, including worktrees placed outside rootDir. - wt update --cleanup example: clarify that only merged stale branches are dropped — unmerged ones are kept and require `wt cleanup --force`. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5771a1a..81f0f8b 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,7 @@ wt list |------|-------------| | `--json` | Output as JSON array | -Output shows each worktree with its path. Badges: `(main)` for the main worktree, `(current)` for the active one, `⚠ dir≠branch` when the worktree directory name does not match its branch name (drift — usually a leftover from a branch rename or a directory moved by hand). The drift badge only appears when a config defines `rootDir` and the worktree lives under it. +Output shows each worktree with its path. Badges: `(main)` for the main worktree, `(current)` for the active one, `⚠ dir≠branch` when the worktree's path does not match `/` (drift — usually a leftover from a branch rename, a directory moved by hand, or a worktree placed outside `rootDir`). The drift badge requires a loadable config; without one (e.g. before `wt init`), drift is not computed. **JSON output** — `--json` writes a single-line JSON array to stdout (no intro/outro), suitable for scripting and AI agents: @@ -248,7 +248,7 @@ wt update feature/parent # Preview what would happen wt update --dry-run -# Fetch, rebase, and drop branches whose remote was deleted — no prompts +# Fetch, rebase, and drop merged branches whose remote was deleted — no prompts wt update --cleanup ```