Enum Command 

pub enum Command {
    Init {
        preset: Option<String>,
        list_presets: bool,
        show: bool,
    },
    List {
        format: ListFormat,
        detect_pr: bool,
    },
    Create {
        branch_type: String,
        issue: String,
        desc: String,
        no_bootstrap: bool,
        reuse_branch: bool,
        skip_hooks: Option<String>,
        repo: Option<String>,
    },
    Pr {
        render: bool,
        draft: bool,
        base: Option<String>,
    },
    Review {
        number: u64,
        name: Option<String>,
        bootstrap: bool,
        skip_hooks: Option<String>,
    },
    New {
        branch_type: String,
        desc: String,
        no_bootstrap: bool,
        reuse_branch: bool,
        skip_hooks: Option<String>,
    },
    Remove {
        pattern: String,
        delete_branch: bool,
        dry_run: bool,
        force: bool,
        skip_hooks: Option<String>,
    },
    Path {
        pattern: String,
        format: OutputFormat,
    },
    Bootstrap {
        target: Option<String>,
        skip_hooks: Option<String>,
    },
    Sync {
        pattern: Option<String>,
        merge: bool,
    },
    Prune {
        dry_run: bool,
    },
    Doctor {
        format: OutputFormat,
    },
    Daemon {
        socket: Option<PathBuf>,
        poll_ms: u64,
    },
    Statusline {
        socket: Option<PathBuf>,
        watch: bool,
    },
    Types {
        gitmoji: bool,
    },
    CommitPrefix {
        branch: Option<String>,
        unicode: bool,
    },
    Hooks {
        action: HooksAction,
    },
    Completions {
        shell: Shell,
    },
    ShellInit {
        shell: InitShell,
    },
    Switch,
    Tmux {
        pattern: String,
        split: bool,
    },
    Zellij {
        pattern: String,
        split: bool,
    },
    Link {
        target: LinkTarget,
        number: u64,
        worktree: Option<String>,
    },
    Unlink {
        target: LinkTarget,
        worktree: Option<String>,
    },
    Open {
        target: LinkTarget,
        worktree: Option<String>,
        print_url: bool,
    },
    Status {
        worktree: Option<String>,
        json: bool,
    },
    Labels {
        action: LabelsAction,
    },
    Milestones {
        action: MilestonesAction,
    },
    Trust {
        action: TrustAction,
    },
    Aliases {
        action: AliasesAction,
    },
    Config {
        action: ConfigAction,
    },
    History {
        limit: usize,
        all: bool,
    },
    Undo {
        bootstrap: bool,
    },
    Tui {
        action: TuiAction,
    },
    Theme {
        action: ThemeAction,
    },
    Exec {
        slugs: Vec<String>,
        profile: Option<String>,
        jobs: Option<u32>,
        command: Vec<String>,
    },
    Clean {
        slugs: Vec<String>,
        profile: Option<String>,
        yes: bool,
    },
}

Variants

Init

Write a .gwm.toml to the current repo, optionally from a stack preset.

Fields

preset: Option<String>

Seed an opinionated .gwm.toml for a known stack (e.g. laravel, node/nuxt, rust, go, python-uv). Omit for the generic documented template. Run gwm init --list-presets to see them all.

list_presets: bool

List the built-in presets with one-line descriptions and exit (writes nothing, needs no git repo).

show: bool

Print the resolved preset to stdout instead of writing .gwm.toml — handy for diffing a preset against an existing config.

List

List worktrees in the current repo.

Fields

format: ListFormat

Output format. names prints one worktree name per line (for shell completion).

detect_pr: bool

Add a PR column, auto-detecting each worktree’s pull request via gh pr list --head <branch> (issue #181). Off by default: it makes one gh call per worktree, so the plain listing stays network-free. Ignored with --format names.

Create

Create a new worktree (and matching branch).

Fields

branch_type: String

Branch type (feat, fix, hotfix, docs, test, refactor, chore, perf, ci, build).

issue: String

Issue number (digits only).

desc: String

Short description (kebab-case, will be normalized).

no_bootstrap: bool

Skip bootstrap after creation.

reuse_branch: bool

Attach the new worktree to an already-existing local branch of the same name instead of refusing (issue #99). Off by default — a pre-existing branch ends gwm create with an error naming the stale tip so the user can audit it.

skip_hooks: Option<String>

Skip lifecycle hooks for comma-separated phases (e.g. pre_create,post_create).

repo: Option<String>

In workspace mode (--workspace <dir>), which child repo gets the new worktree (issue #36). Required there to disambiguate; ignored in single-repo mode, where the worktree always lands in the discovered repo.

Pr

Render the PR body from [pr_template] (issue #84), then gh pr create unless --render is passed.

Without --render, the rendered Markdown is written to a temp file and shelled out to gh pr create --title <subject> --body-file <tmp> --head <branch> (plus --draft and --base when specified). The body resolution honours [pr_template.by_type.<type>] (inline body wins over per-type path), then [pr_template].default as a fallback.

Placeholders substituted by the template engine: {type} {issue} {desc} {base} {head} {repo} {commits} — git log --pretty='- %s' base..head {files_changed} — git diff --stat base..head, capped 30 lines

Fields

render: bool

Render the body to stdout instead of creating the PR. The output is suitable for piping into gh pr create --body-file -.

draft: bool

Create the PR as a draft (shells out to gh pr create --draft). Ignored when --render is set.

base: Option<String>

Override the base ref to compare against (defaults to the resolved trunk from [doctor].trunks, then main).

Review

Materialise an existing GitHub PR into an isolated worktree (issue #308).

Resolves the PR head via gh and fetches origin’s universal refs/pull/<N>/head ref — cross-fork aware, and valid for PRs in any state (open / draft / closed / merged) — into a local review/pr-<N>-<author>-<slug> branch, attaches a worktree, and links the PR so the sidebar / CI indicator light up immediately. Tear down with gwm remove <dir> --delete-branch like any worktree.

Safe-by-default: bootstrap and lifecycle hooks are NOT run, because a review worktree holds a contributor’s (possibly fork) code and those steps execute commands against it (npm install, composer install, direnv allow, post_create hooks …) — i.e. arbitrary code. Pass --bootstrap to opt in once you trust the PR enough to set it up.

Fields

number: u64

PR number to review (digits only).

name: Option<String>

Override the local review branch name (defaults to review/pr-<N>-<author>-<slug>). The worktree directory is derived from this name (slashes become dashes).

bootstrap: bool

Run bootstrap + lifecycle hooks against the PR’s code after creation. Off by default — these execute commands the PR can influence, so it’s opt-in (see the command help for the security rationale).

skip_hooks: Option<String>

Skip lifecycle hooks for comma-separated phases (e.g. pre_create,post_create).

New

Create a GitHub issue from templates, then create its worktree.

Fields

branch_type: String

Branch type (feat, fix, hotfix, docs, test, refactor, chore, perf, ci, build).

desc: String

Short description (kebab-case, will be normalized).

no_bootstrap: bool

Skip bootstrap after creation.

reuse_branch: bool

Attach the new worktree to an already-existing local branch of the same name.

skip_hooks: Option<String>

Skip lifecycle hooks for comma-separated phases (e.g. pre_create,post_create).

Remove

Remove a worktree by fuzzy name match.

Fields

pattern: String

delete_branch: bool

Also delete the branch.

dry_run: bool

Print the resolved worktree (name + path + branch + would-delete-branch flag) without touching anything. Exit code 0. If the pattern is ambiguous, the same non-zero candidate-list error fires as in the destructive form — --dry-run only suppresses destruction, not resolution failures. Issue #31.

force: bool

Emergency removal mode: skip pre_remove and post_remove hooks.

skip_hooks: Option<String>

Skip lifecycle hooks for comma-separated phases.

Path

Print the on-disk path of a worktree (use $(gwm path …) to cd into it).

Also available as gwm cd <pattern> — same semantics, framed for the cd flow. Pair with gwm shell-init <shell> for a one-line wrapper.

Fields

pattern: String

format: OutputFormat

Output format. json emits { name, path, branch } (issue #38); the default text prints the bare path for shell consumption.

Bootstrap

Re-run bootstrap on an existing worktree.

Fields

target: Option<String>

Worktree path or name; defaults to CWD.

skip_hooks: Option<String>

Skip lifecycle hooks for comma-separated phases.

Sync

Fetch + rebase (or merge) a worktree’s branch onto its upstream.

Resolves the target worktree (defaults to the CWD worktree when no pattern is given), runs git fetch for its upstream’s remote, then rebases the branch onto the upstream — or merges with --merge. Reports the outcome with the same ✓ / ! / ✗ sigils as the rest of gwm.

Refuses up front on a dirty working tree (commit or stash first) and on a branch with no upstream configured. A conflicting rebase/merge is aborted so the worktree stays usable, and the user is told to reconcile by hand. Issue #24.

Fields

pattern: Option<String>

Worktree name/pattern; defaults to the worktree containing the CWD.

merge: bool

Merge the upstream instead of rebasing onto it.

Prune

Prune stale worktree references (admin files without a working dir).

Fields

dry_run: bool

List the prunable worktrees (name + path + reason) without touching the admin entries. Exit code 0. Useful for piping into a confirmation script before running the destructive form. Issue #31.

Doctor

Diagnose the gwm setup (config, env, worktree state).

Exit code 0 if all green, 1 if any warning, 2 if any failure — suitable for CI / pre-commit hooks.

Fields

format: OutputFormat

Output format. json emits the checks array plus aggregate severity / exit_code (issue #38); the default text prints the sigil-prefixed report. The process exit code is identical either way.

Daemon

Run a long-running JSON-RPC 2.0 daemon over a unix domain socket.

Editors, statusbars, and tooling connect once and call list / doctor / path, or subscribe for pushed worktrees.changed notifications — instead of spawning gwm per query (issue #38). Newline-delimited JSON, one request and one response per line.

Unix-only and built behind the default-on daemon feature; on other platforms / --no-default-features builds the command exits with an explanatory error.

Fields

socket: Option<PathBuf>

Socket path to bind. Defaults to $XDG_RUNTIME_DIR/gwm.sock, falling back to $TMPDIR, then /tmp.

poll_ms: u64

Worktree-state poll interval in milliseconds for subscribe push notifications. Lower = faster updates, more git scans. This MVP polls rather than watching the filesystem (no notify dep). Must be ≥ 1: 0 would spin a subscribe loop with no wait, re-scanning git as fast as the CPU allows (issue #38 review).

Statusline

Print a compact one-line worktree summary for shell prompts (issue #309).

The first real consumer of gwm daemon: it connects to the daemon’s unix socket, asks for the worktree set, and renders a single line — active branch, worktree count, dirty / ahead / behind, linked issue / PR — suitable for a tmux / starship / zsh statusline. With --watch it subscribes to the daemon’s worktrees.changed stream and reprints on every change (one line per update).

Needs a running gwm daemon (one per repo). When none is reachable it prints an empty line and exits 0, so a prompt substitution degrades to nothing instead of erroring. A CI rollup is intentionally not shown — it is not part of the daemon’s stable schema.

Fields

socket: Option<PathBuf>

Daemon socket path. Defaults to the same resolution as gwm daemon: $XDG_RUNTIME_DIR/gwm.sock, then $TMPDIR, then /tmp.

watch: bool

Stream live updates: subscribe to worktrees.changed and reprint the line on every change instead of printing once and exiting.

Types

List the supported branch types.

Pass --gitmoji to extend the output with two more columns: the resolved emoji (unicode) and its :shortcode: form (issue #85). The shortcode mapping is the built-in default plus any per-repo overrides under [gitmoji] in .gwm.toml.

Fields

gitmoji: bool

Show the resolved emoji + shortcode for each branch type (issue #85). Without the flag, only name + description are printed — matches the pre-#85 surface.

CommitPrefix

Print the Gitmoji + Conventional Commits prefix for the current (or named) branch (issue #85).

Output shape: :sparkles: feat(#41): — the canonical commit prefix used across this repo (see CONTRIBUTING.md §Commits). --unicode substitutes the shortcode for the real emoji character (e.g. ✨ instead of :sparkles:); useful for shell prompts and the bundled commit-msg hook.

Without --branch, reads the current branch from HEAD via libgit2 — requires the CWD to be inside a git repo.

Fields

branch: Option<String>

Branch name to resolve (e.g. feat/#41-tui-search). When omitted, defaults to HEAD of the current repo.

unicode: bool

Emit the real emoji character (✨) instead of the shortcode form (:sparkles:).

Hooks

Manage git hooks installed by gwm (issue #85).

Currently exposes a single hook: commit-msg, which auto-prepends the resolved Gitmoji + Conventional Commits prefix when the commit message doesn’t already start with one. Hooks are opt-in — gwm never installs them implicitly.

Fields

action: HooksAction

Completions

Generate a shell completion script on stdout.

Install (zsh): gwm completions zsh > $fpath[1]/_gwm Install (bash): gwm completions bash > /etc/bash_completion.d/gwm Install (fish): gwm completions fish > ~/.config/fish/completions/gwm.fish

Fields

shell: Shell

Target shell.

ShellInit

Print a shell wrapper exposing gcd <pattern> (one-line cd into a worktree).

Install (zsh): echo 'eval "$(gwm shell-init zsh)"' >> ~/.zshrc Install (bash): echo 'eval "$(gwm shell-init bash)"' >> ~/.bashrc Install (fish): gwm shell-init fish | source (also add to config.fish) Install (powershell): Invoke-Expression (& gwm shell-init powershell | Out-String)

Fields

shell: InitShell

Target shell.

Switch

Open an interactive picker; print the chosen worktree’s path on stdout.

Same TUI as gwm itself, minus the create / delete / bootstrap actions. The fuzzy filter bar opens immediately so typing narrows the list right away. Press Enter to commit the highlighted pick; Esc / Ctrl-C / q quits without printing anything (exit code 1).

Typically invoked via gcd (no arg) from the bundled gwm shell-init wrapper, which cd’s into the picked worktree in one keystroke. The raw form is cd "$(gwm switch)" (or gwm s, the alias).

Tmux

Open the matched worktree in a new tmux window (current session).

Requires $TMUX to be set — i.e. gwm must be invoked from inside an existing tmux session. Outside a tmux session the command exits non-zero with a clear error rather than spawning a stray server. Use --split to open in a horizontal split of the current pane instead of a new window.

Fields

pattern: String

Fuzzy worktree name pattern (same matcher as gwm path / remove).

split: bool

Split the current pane instead of opening a new window.

Zellij

Open the matched worktree in a new zellij tab (current session).

Requires $ZELLIJ to be set. --cwd on zellij action new-tab needs zellij ≥ 0.40. Use --split to open in a new pane of the current tab instead of a new tab.

Fields

pattern: String

Fuzzy worktree name pattern (same matcher as gwm path / remove).

split: bool

Split the current tab into a new pane instead of opening a new tab.

Link

Link the current (or named) worktree to a GitHub issue or pull request.

The link is stored in git config branch.<name>.gwm-issue (or gwm-pr) — local, per-branch, survives worktree moves. Issue numbers are auto-detected from the <type>/#<N>-<slug> convention when no explicit override is set; gwm link issue <N> overrides that. PR numbers are not auto-detected; link them explicitly with gwm link pr <N>.

Fields

target: LinkTarget

What to link: issue or pr.

number: u64

Number to link (digits only).

worktree: Option<String>

Optional worktree pattern; defaults to the current worktree (CWD).

Unlink

Remove the explicit issue / PR link on the current (or named) worktree.

After gwm unlink issue, auto-detection from the branch name resurfaces if the branch follows <type>/#<N>-<slug>. Idempotent — safe to run when nothing is linked.

Fields

target: LinkTarget

What to unlink: issue or pr.

worktree: Option<String>

Optional worktree pattern; defaults to the current worktree (CWD).

Open

Open the linked issue or PR in the browser.

Uses the OS opener (open on macOS, xdg-open on Linux, explorer on Windows). Pass --print-url to emit the URL on stdout instead — useful for piping, testing, and headless shells.

Fields

target: LinkTarget

What to open: issue or pr.

worktree: Option<String>

Optional worktree pattern; defaults to the current worktree (CWD).

print_url: bool

Print the URL on stdout instead of spawning the browser.

Status

Show the issue / PR link and (when gh is available) live GitHub status.

Shells out to gh issue view and gh pr view to fetch state, title, labels, and CI rollup. Without gh (or outside a GitHub repo), prints only the local link. --json emits a stable schema for scripting.

Fields

worktree: Option<String>

Optional worktree pattern; defaults to the current worktree (CWD).

json: bool

Emit JSON instead of the human-readable summary.

Labels

Manage the declarative GitHub label set from .gwm.toml (issue #81).

Declares the desired label set under [[labels]] in .gwm.toml, then pushes it to the upstream origin remote via gh label create --force. Without a [[labels]] block, both subcommands are no-ops (0 labels declared, nothing to push).

Fields

action: LabelsAction

Milestones

Manage the declarative GitHub milestone set from .gwm.toml (issue #82).

Declares the desired milestone set under [[milestones]] in .gwm.toml, then pushes it to the upstream origin remote via gh api repos/:owner/:repo/milestones (no native gh milestone subcommand exists). Without a [[milestones]] block, both subcommands are no-ops (0 milestones declared, nothing to push).

Fields

action: MilestonesAction

Trust

Manage the TOFU trust ledger for .gwm.toml files (issue #95).

gwm runs [[bootstrap.command]] lines from .gwm.toml under the user’s privileges — equivalent to curl … | sh against the repo author. The trust ledger at ~/.config/gwm/trust.toml (override via $GWM_TRUST_LEDGER) records the (origin URL, sha256 of .gwm.toml) tuples the user has approved, so subsequent runs skip the prompt. Hash drift (any byte changes in .gwm.toml) re-prompts — see the module-level comment in src/trust.rs for the threat model.

Fields

action: TrustAction

Aliases

List the resolved CLI aliases (built-in + repo + user). Issue #86.

gwm aliases list surfaces every alias reachable from gwm <name>, grouped by source: built-in (clap visible_alias set), repo (.gwm.toml), user (~/.config/gwm/aliases.toml). The resolution chain favours repo aliases over user aliases when both declare the same name, but both rows are still printed so the user can see what’s being shadowed.

Fields

action: AliasesAction

Config

Read, edit, and validate .gwm.toml values (issue #89).

Fields

action: ConfigAction

History

List the recent destructive operations recorded by gwm (issue #29). One line per op, newest first, with timestamp, kind, and worktree name.

Defaults to the current repo only — pass --all to list ops across every repo in the journal. The journal file lives at $GWM_HISTORY_FILE if set, otherwise $XDG_DATA_HOME/gwm/history.toml.

Fields

limit: usize

Maximum number of entries to print (newest first). Default 20.

all: bool

Show ops across every repo, not just the current one. Useful for power users grepping the journal for forensic purposes.

Undo

Undo the most recent destructive operation recorded for the current repo (issue #29). Recreates the branch at the saved OID, re-adds the worktree at the saved path, then drops the entry from the journal.

Pass --bootstrap to re-run the per-worktree bootstrap after the resurrection (off by default — bootstrap can be expensive and the user often just wants the directory back).

Fields

bootstrap: bool

Re-run bootstrap after the worktree is re-added. Off by default to keep undo cheap.

Tui

TUI introspection / debugging subcommands (issue #87).

Today exposes a single child — keys — which prints the resolved keymap (built-in defaults layered with [tui.keys] overrides from .gwm.toml). Reserved as a sub-tree so future TUI knobs (gwm tui themes, gwm tui dump-state, …) have a stable home without further crowding the top-level surface.

Fields

action: TuiAction

Theme

TUI theme subcommands (issue #33).

gwm theme list prints the names of every built-in preset. gwm theme show <name> dumps the preset as a [theme] TOML block the user can paste into .gwm.toml.

Fields

action: ThemeAction

Exec

Run a shell command in each worktree, sequentially (issue #313).

gwm exec -- git fetch runs in every non-main worktree; pass slugs before -- to scope it: gwm exec feat-1 fix-2 -- cargo check. Prints a per-worktree ✓ / ✗ rollup and exits non-zero if any worktree’s command failed. Everything after -- is forwarded verbatim (flags and all). This is the user’s own command against their own worktrees — no bootstrap trust gate applies (#95).

Fields

slugs: Vec<String>

Worktree slugs to target (fuzzy match, before --). Empty = all non-main worktrees.

profile: Option<String>

Run a saved [exec.profiles.<name>] command instead of an inline -- <cmd> (issue #324). Mutually exclusive with an inline command; an unknown name exits 1.

jobs: Option<u32>

Bounded parallelism (issue #324). 1 (default) runs sequentially with live, inherited output; > 1 runs up to N worktrees at once, capturing each one’s output and printing it as a block at the end. Wins over a profile’s / [exec]’s jobs.

command: Vec<String>

Command to run, after --. Everything past -- is forwarded verbatim, e.g. gwm exec -- git log --oneline. Provide either this or --profile, never both, and at least one.

Clean

Report (and optionally reclaim) heavy build artifacts across worktrees (issue #313).

Scans each worktree for target/, node_modules/, dist/, build/ and prints the reclaimable size per worktree. Report-only by default; pass --yes to actually delete. Scope to a subset with slug positionals: gwm clean feat-1. Deliberately not journaled into gwm history (#29) — the artifacts are regenerable.

Safety: --yes only deletes directories git treats as ignored. A non-ignored dist/ / build/ (tracked or hand-authored, hence non-regenerable) is reported as skipped, never removed.

Fields

slugs: Vec<String>

Worktree slugs to target (fuzzy match). Empty = all non-main worktrees.

profile: Option<String>

Reclaim a saved [clean.profiles.<name>] directory set (a COMPLETE set that replaces the built-ins) instead of target/node_modules/ dist/build (issue #324). An unknown name exits 1. Without it, [clean.profiles.default] is used when present, else the built-ins.

yes: bool

Delete the listed artifacts instead of only reporting them.

Trait Implementations

impl Debug for Command

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for Command

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for Command

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand