Skip to content

user-guide.md

Latest commit

 

History

History
305 lines (193 loc) · 11.1 KB

user-guide.md

File metadata and controls

305 lines (193 loc) · 11.1 KB
Raw

User Guide

Installation and upgrades

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/nettee/worktree-kit/main/scripts/install.sh | sh

The installer downloads the matching GitHub release asset, verifies its checksum, installs wtk into ${WTK_INSTALL_DIR:-$HOME/.local/bin}, and creates ~/.wtk/config.toml from a default copy template when it does not already exist. It prints PATH and completion setup guidance after verifying wtk --version.

Upgrade an existing release install in place:

wtk upgrade

Local source install for development machines:

sh scripts/install-local.sh

The local installer also creates ~/.wtk/config.toml from the same default template when it does not already exist.

Check the installed version:

wtk --version

Common Workflows

Creating and checking out worktrees

Create a new branch in a linked worktree:

wtk new feature/login

Check out an existing branch or ref in a linked worktree:

wtk checkout feature/existing

By default, wtk uses the Sibling Layout: a repository's linked worktrees live next to the main worktree using names like <repo>-wt-<branch-slug>.

Commands that create linked worktrees copy globally configured ignored files from the main worktree into the new worktree at the same Git-root-relative paths. Copy Patterns use gitignore-style syntax except negation (!) and only select files or symlinks that Git reports as ignored; tracked files are never copied by Copy Patterns. When matching ignored files are copied, wtk prints one concise summary such as copied 12 ignored files.

Copy Patterns are configured only in global ~/.wtk/config.toml. Repo-local .wtk/config.toml cannot contain copy and fails fast if it does. Without a global copy list, wtk copies no ignored files by default. The default config template is:

copy = [
  "**/.env",
  ".agents/",
]

For standalone wtk new, success is reported before asynchronous worktree initialization finishes copying ignored files into the new worktree. wtk prints info lines when that background initialization starts and where its temporary log file is written.

If a new worktree looks like a pnpm repo (pnpm-lock.yaml or pnpm-workspace.yaml at the root), wtk new starts pnpm install after the success message instead of waiting for it to finish first. Standalone wtk new does that from the asynchronous initializer, and coordinated wtk new --ag ... starts asynchronous installs for the primary and auxiliary worktrees after the coordinated worktree is created. Wait for the reported log file to finish before assuming ignored files or dependencies are ready.

Listing and status

List visible worktrees:

wtk list

wtk list is optimized for scanning. The default output is a compact table with the worktree directory name, branch, relative HEAD commit time, state labels, and short HEAD. It does not print absolute paths by default. Rows are sorted by the current HEAD commit's committer time, newest first; dirty state is shown as a label but does not affect sorting.

Use JSON output for scripts:

wtk list --json

JSON includes absolute paths, full HEADs, timestamps, labels, diagnostics, and Auxiliary Ref details.

Print current repository and worktree status as YAML:

wtk status

wtk status validates generated refs for the current Primary Repository worktree when auxiliary state is recorded.

Moving work out and back in

Move the current main-worktree branch to a linked worktree:

wtk send-out

send-out must run from the main worktree. It switches the main worktree back to the selected base branch and creates a linked worktree for the branch that was previously checked out.

Bring a linked worktree branch back into the main worktree:

wtk bring-in feature/login

bring-in must run from the main worktree. It finds the linked worktree for the named branch, removes that linked worktree, and switches the main worktree to the branch.

Both flows require the relevant worktrees to be clean. Worktrees with auxiliary state reject send-out and bring-in because those commands do not define an atomic multi-repository move.

Auxiliary Groups and coordinated worktrees

The Primary Repository is the repository opened directly for a task. An Auxiliary Repository is another repository exposed from the Primary Repository when a task needs coordinated code changes or PRs outside the Primary Repository.

Create a local Auxiliary Group from the Primary Repository:

wtk auxiliary-group add full-stack /absolute/path/to/api /absolute/path/to/web

wtk ag add is a shorthand for wtk auxiliary-group add. Group creation resolves each repository path to a Git main worktree, derives the Auxiliary Repository Ref name from the repository directory name, creates or reuses [auxiliaries.<name>], and writes [auxiliary-groups.<group-name>] in .wtk/config.toml.

Inspect configured groups:

wtk ag list

Remove a group definition:

wtk ag remove full-stack

Removing a group deletes that group's [auxiliary-groups.<group-name>] entry from .wtk/config.toml. Existing [auxiliaries.*] entries remain in the config and may be reused by other groups later.

The generated config shape is:

[auxiliaries.api]
repository = "/absolute/path/to/api"

[auxiliaries.web]
repository = "/absolute/path/to/web"

[auxiliary-groups.full-stack]
auxiliaries = ["api", "web"]

Create a coordinated worktree by selecting one or more groups:

wtk new feature/full-stack --ag full-stack
wtk new feature/full-stack --auxiliary-group full-stack

No selected Auxiliary Groups is the standalone case. With selected groups, wtk new creates the Primary Repository worktree plus matching Auxiliary Repository worktrees for the same branch. The Primary Repository worktree receives generated refs/<auxiliary-name> entries pointing to the Auxiliary Repository worktrees. .wtk/worktrees.json stores the expanded Auxiliary Repository state by absolute Primary Repository worktree path; changing the config later does not mutate existing worktrees.

Coordinated Primary Repository worktrees also receive a generated WTK-AUXILIARY.md file that lists the concrete Auxiliary Repository refs and targets. WTK keeps /.wtk/, /refs/, and /WTK-AUXILIARY.md ignored through .git/info/exclude.

wtk list shows ordinary and coordinated Primary Repository worktrees together and summarizes Auxiliary Ref health, such as refs 2/2 ok or refs 1/2 broken. wtk remove removes the coordinated set. wtk remove --delete-branch removes primary and auxiliary worktrees and branches after preflight checks.

WTK loads config with this precedence:

  1. Legacy repo config at $(git rev-parse --git-common-dir)/wtk/config.toml when repo-local .wtk/config.toml is absent
  2. Global config at ~/.wtk/config.toml
  3. Repo-local config at .wtk/config.toml

Repo-local config overrides global config when both set the same copy list. For backward compatibility, WTK still accepts the legacy [groups.<group-name>] key in existing config files, and reads the legacy $(git rev-parse --git-common-dir)/wtk/worktrees.json file when .wtk/worktrees.json is absent.

Base branch selection

wtk new selects the base for the new branch by this precedence:

  1. --base
  2. --from-current / -C, which uses the branch checked out in the current worktree
  3. git config worktree-kit.mainBranch
  4. origin/HEAD
  5. one unambiguous local branch among main, master, trunk, develop

Set an explicit default when needed:

git config worktree-kit.mainBranch trunk

Shell completion

wtk completion bash > /usr/local/etc/bash_completion.d/wtk
wtk completion zsh > "${fpath[1]}/_wtk"
wtk completion fish > ~/.config/fish/completions/wtk.fish
wtk completion powershell > wtk.ps1

Failure behavior

Dirty worktrees, malformed Auxiliary Group config or worktree state, missing generated refs, branch mismatches, ambiguous main branch detection, missing Git context, failed Git commands, ignored local config copy failures, and clipboard failures are reported directly. If Git succeeds and a later required step fails, wtk exits non-zero so the partial failure is visible.

Every command prints the underlying git commands it runs. Successful commands copy the useful path or branch payload to the clipboard. Use --no-clipboard in CI or headless environments.

Command reference

wtk new

wtk new <branch> [--path <path>] [--base <branch>] [--from-current] [--ag <group>] [--auxiliary-group <group>] [--no-clipboard]

Creates a new branch in a linked worktree.

--ag and --auxiliary-group may be repeated to select one or more Auxiliary Groups. --path is not supported with Auxiliary Groups. --base and --from-current cannot be combined.

wtk create

wtk create <branch> [--path <path>] [--base <branch>] [--from-current] [--ag <group>] [--auxiliary-group <group>] [--no-clipboard]

Compatibility alias for wtk new.

wtk checkout

wtk checkout <branch> [--path <path>] [--no-clipboard]

Checks out an existing branch or ref in a linked worktree.

wtk status

wtk status

Prints current repository and worktree status as YAML.

wtk list

wtk list [--json]

Lists visible worktrees in a compact table, or prints machine-readable JSON with --json.

wtk delete

wtk delete

Opens an interactive terminal-only multi-select delete flow. Select linked worktrees with Space, press Enter, review the absolute-path summary, then type exactly Y to delete. Branches are preserved. Dirty selected worktrees are force-removed after confirmation. Selecting a coordinated Primary Repository worktree deletes its recorded coordinated set.

wtk remove

wtk remove [path] [--delete-branch] [--no-clipboard]

Removes a linked worktree. With coordinated worktrees, removes the coordinated set. --delete-branch also deletes the relevant branch after preflight checks.

wtk send-out

wtk send-out [--path <path>] [--base <branch>] [--no-clipboard]

Moves the current main-worktree branch to a linked worktree. It refuses the selected base branch, dirty main worktrees, ambiguous main branch detection, and worktrees with auxiliary state.

wtk bring-in

wtk bring-in <branch> [--no-clipboard]

Moves a linked worktree branch back into the main worktree. It requires the main worktree and the linked worktree to be clean, and it rejects worktrees with auxiliary state.

wtk auxiliary-group

wtk auxiliary-group add <group-name> <repo-path>...
wtk auxiliary-group list
wtk auxiliary-group remove <group-name>

Manages Auxiliary Groups. wtk ag is an alias for wtk auxiliary-group.

Auxiliary repository paths must resolve to main worktrees. Duplicate repositories are rejected.

wtk upgrade

wtk upgrade

Downloads and installs the latest GitHub release over the current release-binary install.

wtk completion

wtk completion <bash|zsh|fish|powershell>

Generates a shell completion script.