Skip to content

Changelog

Unreleased

  • Remove inactive per-worktree-path creation lock files on macOS and Linux after ownership is released. kwt doctor --fix also clears leftovers from earlier releases or interrupted processes while preserving locks that are still held. Restart kwt processes after upgrading before running the cleanup; mixed old and new lock protocols are not supported. Windows retains the existing persistent-file behavior.
  • Imported pull-request worktrees now preserve both sides and diff3 markers when a later merge encounters a text conflict. PR import now requires Git 2.42.0 or newer on macOS and Linux, or Git for Windows 2.53.0.windows.3 or newer.
  • Recognize bare-container repositories where a .bare/ control directory manages a checked-out main/ worktree and flat sibling worktrees. kwt projects add accepts the container or any of its worktrees, .bare/ stays out of worktree inventory, and generated worktrees preserve the flat sibling layout using the sanitized branch name. An explicit destination path still takes precedence.
  • Deliver each SSH askpass protocol frame in a single socket write, so a helper answering a prompt with no hint text can no longer fail spuriously when the responder closes the connection first.

0.5.1

2026-08-29

kwt 0.5.1 is the publishable build of the 0.5 release. The original 0.5.0 tag did not produce release artifacts because its verification jobs depended on the host runner's process table and path syntax. This release makes those checks portable without changing the CLI's removal safeguards.

Applications that embed kwt can now supply RemovalServiceOptions.ProcessGuard when they already have their own way to detect processes that use a worktree. kwt's default remains unchanged: removal stops when a process uses the worktree or when that check is inconclusive, unless the caller explicitly uses Force.

Compare v0.5.0...v0.5.1

0.5.0

2026-08-28

kwt 0.5.0 makes the complete worktree lifecycle safer to manage and easier to automate. It adds practical maintenance and change inspection, moves shared state behind a local daemon, and exposes the same core services to applications that embed kwt.

Maintain worktrees safely

  • Find broken worktree metadata and stale project registrations with kwt doctor. The command is read-only by default. kwt doctor --fix makes only repairs that kwt can prove are unambiguous, then scans again and leaves uncertain cases for you to review.
  • Preview expired or merged worktrees before removing them with kwt prune --expired --dry-run or kwt prune --merged --dry-run. Merged pruning requires a confirmed GitHub pull request and preserves the local branch. A dirty merged worktree requires interactive confirmation, so an unattended cleanup fails closed instead of discarding work.
  • See progress, the current phase, and an estimated completion time during longer doctor and prune runs. The terminal dashboard stays responsive while removals wait in a first-in, first-out background queue.
  • Avoid deleting a checkout from under a shell, agent, or other local process. Removal now stops when a live process is using the worktree as its current directory and reports the blocking process IDs. kwt remove --force remains the explicit override.
  • Treat a worktree as removed when Git has deregistered it but could not delete every file. kwt finishes its guarded bookkeeping and reports cleanup_incomplete with the remaining path instead of hiding the partial result behind a generic failure.

Run dependable workspaces

  • Register and open ordinary directories as workspaces, even when they are not Git repositories. Directory workspaces use the same layouts, structured inventory, and session-starting commands as worktree workspaces.
  • Use one current view of projects and worktrees across the CLI and dashboard. A local kwt daemon now owns inventory and worktree removal, while the dashboard can paint its last known view immediately and refresh the active project first.
  • Keep kwt sessions separate from tmux sessions you manage yourself. New ordinary workspaces and kwt tmux run jobs use the dedicated tmux -L kwt server. kwt can adopt a verified existing workspace session from the default server during the transition, but it does not create a new session there.
  • Resolve a workspace session from the exact observed worktree generation, so replacing or switching a checkout at the same path cannot silently attach a client to the old workspace.
  • Import a pull request again after its old worktree has been removed. kwt now reuses the preserved local branch when it creates the replacement worktree.

Automate with confidence

  • Inspect the exact changed files in one registered worktree with kwt changes [path]. Human output separates staged and working-tree changes; --json returns a stable, deterministic list including untracked files, renames, copies, deletions, and conflicts. kwt discards the result if the worktree is replaced while Git is reading it.
  • Follow long-running daemon work through ordered, reconnectable operation events. Stable error codes distinguish ownership, compatibility, transport, stale-state, and unknown-outcome failures without making clients parse prose.
  • Bind destructive or identity-sensitive actions to the inventory that a client actually reviewed. Guarded project removal, worktree creation, protected attachment, and pull-request import stop with a retryable error if the project registration, worktree generation, or session changed first.
  • Remove stale project metadata noninteractively with kwt projects remove <path> --json. This command removes only the registry entry; it never deletes a repository, worktree, or tmux session.

Embed and connect kwt

  • Build on public Go services for project and worktree inventory, removal, change inspection, operations, typed errors, and SSH. These are supported kwt building blocks; Ghosthub is one consumer, not the only intended client.
  • Use the authenticated local daemon when a separate process needs current inventory, lifecycle ownership, ordered progress, or stable failure details. Remote clients still run kwt on the remote machine and connect only to that machine's loopback daemon.
  • Attach clients through an explicit tmux session endpoint. JSON records carry session_name, tmux_socket_name, and tmux_attach_mode, so a client does not have to infer whether a workspace uses the dedicated server, an adopted default-server session, or a protected socket. These endpoint fields are a client contract, not daemon tmux routes.
  • Resolve OpenSSH routes and let kwt hold generation-bound connection leases. Clients can review structured host-key prompts, keep direct and ProxyJump connections alive, run commands, and copy files without reconstructing kwt's private SSH arguments. Unattended connections require already trusted keys; reviewed connections use an explicit host-key policy.

Upgrade notes

  • Bare kwt prune no longer repairs structural metadata. Use kwt doctor --fix for that work.
  • kwt prune --expired now applies only to live worktrees covered by an expiration policy. An already-absent path reports doctor_required and points you to kwt doctor --fix instead of silently removing its registry entry.
  • The general minimum remains Git 2.20. kwt doctor, kwt prune --expired, and kwt prune --merged require Git 2.31.
  • Building from source, including go install, now requires Go 1.27. Supported macOS versions start at macOS 13.
  • KWT_HOME now isolates registry.json as well as configuration and pull-request state. If you move an existing installation to a new KWT_HOME, copy the old registry.json explicitly; kwt will not import it automatically.
  • Ordinary workspaces now use kwt's dedicated tmux server. Upgrade cooperating kwt clients, including embedded clients such as Ghosthub, together during the transition so an older client does not create a parallel default-server session.

Fixes

  • Project listings omit registered paths that no longer exist, while retaining their stored identity so registering the checkout at its new path can still relocate the project.
  • Empty project registries are repaired without overwriting newer or concurrent registration changes.
  • Pull-request re-import works after the previous worktree was removed and its local branch was preserved.

Compare v0.4.0...v0.5.0

0.4.0

2026-08-02

kwt 0.4.0 expanded the project from creating new-branch worktrees into managing workspaces from existing branches and pull requests. It also made worktree identity and tmux handoff safer for both interactive use and automation.

Start from work that already exists

  • Create a worktree from an existing local or remote branch with kwt add --from. The dashboard offers the same branch search with b, and automation can read the normalized choices from kwt branches --json.
  • Open exact primary or linked-worktree paths outside the configured global worktree directory. kwt open <path> --start-session can prepare a missing workspace without attaching to it.
  • Import pull requests with the host's configured Git credential helpers and keep their workspace history when a GitHub repository is renamed or transferred.

Keep workspace identity intact

  • Bind destructive worktree actions to the checkout's durable creation identity. A replacement checkout at the same path is not removed because of a stale confirmation.
  • Finish bookkeeping when Git deregisters a worktree but cannot complete the final directory removal, while continuing to preserve ordinary dirty-worktree errors.
  • Create missing protected and ordinary tmux sessions before attachment. On Unix-like systems, kwt hands an external attachment directly to tmux instead of remaining resident for the session's lifetime; Windows keeps the child process behavior.
  • Make inventory easier to read by labeling primary checkouts with [primary] and detached worktrees with their abbreviated commit, including in multi-machine views.

Install a released build

  • Download checksummed archives for macOS, Linux, and Windows on AMD64 and ARM64. Development installs also use the shared GOPATH binary directory by default, so the same kwt binary resolves across repositories.

Compare v0.3.0...v0.4.0

0.3.0

2026-07-27

kwt 0.3.0 established the vMAJOR.MINOR.PATCH release line and made project registration available to automation. kwt projects add <path> --json lets a new machine register an existing checkout without opening the dashboard or editing configuration by hand. Repeating the command converges on one canonical project entry instead of creating duplicates.

This release remains installable through the Go module proxy. It predates the automated GitHub archive and checksum pipeline introduced in v0.4.0.