/.git:

/.git -w \ -e GIT_CONFIG_COUNT=2 -e GIT_CONFIG_KEY_0=safe.directory -e GIT_CONFIG_VALUE_0= \ -e GIT_CONFIG_KEY_1=safe.directory -e GIT_CONFIG_VALUE_1=

/.git \ ``` **Host paths are mirrored, and the main checkout's gitdir is mounted alongside.** This is the point of the feature rather than a detail. A linked worktree's `.git` is not a directory, it is a **file** holding the **absolute host path** of `

/.git/worktrees/`. Mount only the worktree and that path does not exist inside the container: no `git status`, no `git describe` to stamp a version, no commit, no hook, and no coding agent that touches git. Mounting the main checkout's `.git` at its own host path fixes it, and once a host-absolute path has to be reproduced anyway, a `/workspace` mount point buys nothing, so `-w` is the worktree's own path and `{path}` / `GWM_PATH` stay true on both sides. When the gitdir already lives inside the worktree (the main checkout, reachable via an explicit slug), the first mount covers it and the second is skipped. - **Every mounted path is declared `safe.directory`.** With a rootful Docker on Linux the container runs as uid 0 while the bind-mounted tree belongs to you, and git refuses a repository it reads as `dubious ownership`, which would undo the mount above. gwm declares the paths **it mounts itself** through `GIT_CONFIG_*` environment: nothing is written to any config file, and the blanket `*` is never used, so the ownership check stays on for everything else. It is the same fix CI providers apply to their own checkouts. What this does **not** change is file ownership: with a rootful daemon, files the command creates (a `target/`, a `node_modules/`) belong to root on the host. Add `extra_args = ["--user", "1000:1000"]` if that matters to you, keeping in mind that some images expect root (a writable `CARGO_HOME`, `apt-get`). - **`gwm exec` allocates no TTY; the TUI overlay does.** A fan-out over N worktrees has no use for a terminal per container. The TUI exec overlay (`e`) spawns into a real pty, so there the container is started with `-i -t` and a REPL, a debugger or any prompting command keeps working, exactly as it does when the profile runs on the host. - **Not supported on Windows.** The wrapper mirrors host paths, and `C:\…` is neither mountable nor resolvable inside a Linux container. Worse, a linked worktree's `.git` file would still name a drive-letter path, so even a translated mount would leave git unable to answer, which is the one thing this feature exists to guarantee. A profile carrying `[container]` is refused there with a message saying so, rather than handed to `docker run` to fail obscurely. - **argv, never a shell string.** gwm hands `docker`/`podman` an argument vector; nothing is quoted, joined, or re-parsed by a shell at any point. This is an invariant, not a happy consequence (see [GHSA-fffq-vg6f-gxqm](https://github.com/kbrdn1/gwm-cli/security/advisories/GHSA-fffq-vg6f-gxqm), branch-name injection through a shell hook). - **The command is the container's CMD**, so an image with an `ENTRYPOINT` receives it as arguments. `extra_args = ["--entrypoint", ""]` opts out. The stock language images (`rust`, `node`, `golang`, …) declare no entrypoint, so the plain form works for them. - **No `interactive` / TTY knob.** `gwm exec` is a fan-out over N worktrees, where a TTY per container means nothing. It will come with the surfaces that can honour it (the multiplexer windows, the PTY overlay), not here. - **`extra_args` come last, so they win.** A repeated flag overrides gwm's: `["-w", "/workspace"]` moves the working directory. Taking that means owning the consequence: the worktree is still mounted at its host path, so `-w /workspace` points at a directory the container does not have. If you also remount it (`["-v", ":/workspace", "-w", "/workspace"]`), the `.git` file inside it still names the host path, and git will only answer because the gitdir mount is there. - **The container is removed when the TUI overlay closes.** Killing a `docker run` client does **not** stop the container: the daemon owns it, and `--rm` only fires once it exits. So a long command would keep writing to the worktree after the overlay visibly closed. The overlay names its container (`--name gwm---`, carrying gwm's pid so two gwm processes on the same worktree cannot agree on a name and tear down each other's container) and removes it on close, from the worktree, so a relative `runtime` resolves the same way it did on the way in. `--name` in `extra_args` is refused for that reason: a runtime honours the last one it is given, which would leave the teardown removing something else. The `gwm exec` fan-out needs none of this, since it never kills its client mid-run. - **A `:` in the worktree path is refused.** It is legal on Unix but is the field separator of `-v source:destination`, so such a mount cannot be expressed. gwm says so instead of letting the runtime reject the spec with a message about neither the worktree nor gwm. - **For caches, prefer a named volume to a host path.** `.gwm.toml` is committed and travels between machines, so `-v gwm-cargo:/usr/local/cargo/registry` is portable where `/Users/you/.cargo` is not. There is no `~` or `$VAR` expansion in `extra_args`: tokens are passed through verbatim. - **Any Docker-compatible socket works, with nothing to integrate.** OrbStack, Colima, Rancher Desktop, Docker Desktop and native Linux Docker all expose the `docker` CLI; gwm only builds an argv for it. Listing them as "supported runtimes" would be marketing rather than integration. **clean: a profile's `dirs` is a complete set that replaces the built-ins.** `[clean.profiles.].dirs` does **not** add to the built-in `target`/`node_modules`/`dist`/`build`: it **replaces** them wholesale. Each entry must be a **single worktree-relative directory name**, one path component. An absolute path, a `..` traversal, an empty string, a bare `.` (which resolves to the worktree root), a **nested** path like `target/debug`, or a name with **git pathspec metacharacters** (`* ? [ ]` or a leading `:`) is rejected (exit 1). The nesting restriction is deliberate for 1.0 (an intermediate component could be a symlink the scan/delete would follow out of the worktree); the metacharacter restriction keeps the git-ignored / tracked-file safety checks matching the literal directory. A leading `-` is fine. Exact duplicate entries are dropped so a directory is reclaimed once. The safety gate (git-ignored + no tracked files + skip symlinks) still applies to every directory in the set. - `gwm clean` **without** `--profile` uses `[clean.profiles.default]` when present, else the built-in four. `gwm clean --profile ` uses that profile's set; an **unknown** name exits 1. ## `[tui]` Runtime knobs for the worktree TUI. ```toml [tui] # Safety countdown (in seconds) for the delete-confirm overlay when `p` is armed. # Accepts 0..=5; values above 5 are clamped on read. Setting it to 0 keeps the # classic single-keystroke modal even when delete-branch-on-remove is armed. confirm_countdown_secs = 3 # Which side the worktree-details sidebar sits on in the side-by-side layout. # "right" (default, pre-#188 behaviour) or "left". Toggle it live with `v`. sidebar_position = "right" # How the sidebar is arranged relative to the table: "stacked" (default), # "side-by-side", or "auto" (width-driven). Cycle it live with `z`. sidebar_orientation = "stacked" # How panes and sidebar sections are framed: "compact" (default, filled # one-line headers) or "bordered" (the lazygit-style boxes, gwm's layout up # to 1.7). See "layout" below. layout = "compact" # Dim the body of whichever pane does not hold focus. Off by default — it # trades contrast for a stronger "where am I" signal. Applies to both layouts. dim_unfocused = false # Fold the sidebar's Status block onto one line (branch · head · state · # diff · age). On by default; set to false for the labelled four-row block. status_one_line = true # Give the in-TUI note editor (`N`) a vim normal mode. On by default: the # first `Esc` leaves insert, and the second one writes and closes. Set it to # false for the modeless editor, where one `Esc` writes and closes. note_vim = true # What the TUI opens in the multiplexer: "pane" (default), "tab" (a whole # tmux window / zellij tab / herdr tab), or "workspace" (herdr only). mux_open_in = "pane" # Which half a mux pane takes: "right" (default), "down", "left" or "up". # herdr takes only the first two. Only meaningful under mux_open_in = "pane". # Also the direction a CLI `--split` takes. mux_pane_direction = "right" # Command that renders a URL inside the terminal, taking an optional {url} # placeholder. Only used when a multiplexer is detected; unset (the default) # sends every link to the external browser, as gwm always has. terminal_browser = "w3m {url}" # Who places that browser: "overlay" (gwm hosts it in a pane or the PTY # overlay, the default) or "detached" (the browser splits on its own and gwm # only launches it). terminal_browser_open_in = "overlay" # How yanked text reaches the clipboard: "auto" (OSC52 over SSH, host tools # otherwise), "osc52", or "tools". clipboard = "auto" # Periodic worktree-list refresh interval, in seconds. Default 60 keeps the # Issue/PR table state reasonably fresh; set to 0 to disable the auto-refresh # loop entirely (you can still refresh on demand with the `refresh` key). auto_refresh_secs = 60 ``` `sidebar_position` (issue #188) sets the default side of the details sidebar in the **side-by-side** layout: `"right"` (default) or `"left"`. `v` toggles it live in the TUI. The **stacked** layout (table on top, sidebar below) ignores this, since there the sidebar is always at the bottom. An unknown value is a **hard config error at load time**. `sidebar_orientation` (issue #365) sets how the sidebar is arranged relative to the table: | Value | Behaviour | |:------|:----------| | `"stacked"` | Table on top, sidebar below. **Default** since issue #217, because the status pane reads best at full terminal width. | | `"side-by-side"` | Always beside the table, whatever the terminal width. | | `"auto"` | Side-by-side at `>= 120` columns, stacked below that. | `z` cycles it live (`auto` → side-by-side → stacked → `auto`; it was `Space` before #484). Before #365 that live choice was runtime-only and reset on every launch; setting the key here makes it stick. An unknown value is a **hard config error at load time**. It is also exposed in the Settings panel under the **TUI** tab. ### layout `layout` (issue [#545](https://github.com/kbrdn1/gwm-cli/issues/545)) chooses how panes and sidebar sections are framed. A bordered section spends two rows and two columns on its frame plus a third row on its bottom-rule counter; a compact one spends a single row. | | `"compact"` (default) | `"bordered"` | |:--|:--|:--| | Section frame | one filled header line | four rules, title in the top one | | Title | ` ISSUE / PR [F] ` (uppercased) | ` Issue / PR [F] ` | | Counter | right of the header line | bottom rule, right-aligned | | Focus signal | header fill (a darkened `accent` band when focused, `section_bg` otherwise) + a bold title | border colour | | Pane boundary | a `muted` rule between the two panes | the boxes themselves | | Worktrees pane height | its row count, capped at its share | its share of the stacked split | | Modal frame | a filled title band, a `section_bg` footer band, no rules | four rules, title in the top one | | Modal padding | one blank row at each end of the content, one column each side | one blank row and two columns each side | **`"compact"` is the default.** The density is the point: the box rules were the single largest source of wasted space on screen, and the mode buys back two rows and two columns per section. **`"bordered"` reproduces gwm's layout up to 1.7** for users who prefer it. It is deliberately left untouched by the compact-mode refinements — no dimming, no separator rule — so it stays a faithful restore rather than a third look. An inactive header is the `section_bg` [theme role](/tui/themes), an indexed colour rather than a translucent white so it stays readable on a terminal without truecolor, with the title on it in `accent`. The focused one trades the pair ([#605](https://github.com/kbrdn1/gwm-cli/issues/605)): an `accent` band carrying that section tone as its text, bold — the dark-on-colour treatment the version chip and the footer's context anchor already use. The band is `accent` pulled down toward `section_bg`, mixed from the two rather than declared as its own role, so overriding either keeps them in tune; a palette with nothing to mix — an ANSI colour name, whose value belongs to the terminal, or a 256-palette index — keeps `accent` itself, which is the default theme's case. Not `focus`, which is the border tone and *more* saturated. How far it is pulled down is bounded by the dark text on it: the two keep a 3:1 contrast. Neither state uses `muted`: a pane's name is how you find the pane to `Tab` into, so it stays legible when the pane is inactive. Focus adds weight to the whole header line on top of the fill. A span that carries its own colour keeps it on either band — the filter `/` prompt, the Working Tree per-category counts — because the header style is patched onto a span rather than substituted for it. Overlays and modals follow the knob too (issue [#594](https://github.com/kbrdn1/gwm-cli/issues/594)). Compact gives them the same treatment the panes get: the title on a filled band across the first row, no rules on any side, and the row every modal already spends on its key hints painted as a quiet `section_bg` band, which is two rows and four columns back per overlay. Content never sits flush against a band at either end: the frame keeps a blank row under the title, and every modal leaves one above its hints (the four full-size overlays and the note editor gained theirs with #594, in both layouts). The bottom-rule counter a bordered modal carries (the Working Tree's per-category counts) moves to the right of that band, where a compact pane puts its own. A panel floating over content is where a rule earns its keep, which is what the missing rules cost. What replaces them is the ground: while a compact modal is up, everything behind it is darkened, the colours mixed toward black rather than just `DIM`, because `DIM` touches the foreground only and the pane header band directly above a full-size overlay would otherwise read as part of it. A palette with no components to mix keeps `DIM` alone. `bordered` is left alone here as everywhere else: it already has its boundary. An unknown value is a **hard config error at load time**. `layout`, `dim_unfocused`, `status_one_line`, `note_vim`, `mux_open_in`, `mux_pane_direction`, `terminal_browser` and `terminal_browser_open_in` are also exposed in the Settings panel under the **TUI** tab (`4`), where cycling the choice applies live. ### dim_unfocused `dim_unfocused` dims the body of whichever pane does not hold focus. **Off by default**, and it applies to **both** layouts — the signal is about focus, not about how a pane is framed. It ships off because it is a trade-off rather than a strict improvement: the inactive pane's content is still information you may be reading, and dimming costs contrast on a surface that is often a screenshot. Users who move between the two panes constantly get a stronger "where am I" cue by turning it on. The dimming uses the terminal's `DIM` attribute rather than repainting in `muted`, so the body keeps its semantic colours — a dirty branch stays yellow, a staged file stays cyan. A terminal that ignores `DIM` simply renders as if the option were off, where the header fill (compact) or the border colour (bordered) still carries the signal. ### status_one_line `status_one_line` (issue [#547](https://github.com/kbrdn1/gwm-cli/issues/547)) folds the Status block's four values onto a single row. **On by default.** ```text status_one_line = true status_one_line = false feat/#42-webhooks · f9e8a58 · ● dirty … Branch feat/#42-webhooks · f9e8a58 Path ~/cc-worktree/webhooks Created 1w Diff +2 -0 State ● dirty Path ~/cc-worktree/webhooks ``` Four labelled rows for four values of a handful of characters each was the sidebar's largest remaining waste once #545 cut the chrome. The fold buys back three rows and hands them to the panes below. It is a knob rather than a compact-mode behaviour, so it applies under **both** layouts — `bordered` folds too unless you turn this off. The `Path` row is never folded in: a path is the one value long enough that sharing a row would clip the path and whatever joined it. **Segment order is the width policy.** The sidebar does not wrap, so a row wider than the pane is clipped on the right: identity (branch, head) leads because it is what the row is for, and `Created` trails because it is the value the pane can most afford to lose. Every segment keeps the [theme role](/tui/themes) it wears in the labelled block. ### note_vim `note_vim` (issue [#557](https://github.com/kbrdn1/gwm-cli/issues/557)) gives the in-TUI note editor (`N`) a vim normal mode. **On by default.** `N` opens in normal mode, `i` / `I` / `a` / `A` / `o` / `O` enter insert, `Esc` goes back to normal, and the second `Esc` writes and closes. The motions are `hjkl`, `w` / `b` / `e` and their `W` / `B` / `E`, `0` / `^` / `$`, `gg` / `G`, plus `x` and `dd`. The full table is in [TUI → keybindings](/tui/keybindings#vim-normal-mode-557). That second sentence is the cost, so it is worth stating on its own: **the first `Esc` no longer writes and closes**. Set `note_vim = false` and the editor is exactly the one #515 shipped, where every printable is text and one `Esc` writes and closes. It changes no binding: `[tui.keys.modal.note]` holds the same four verbs either way, and an unmodified printable bound to one of them is refused at load time with or without the mode. What it does change is what unbound printables mean, which is why the modal title carries a `NORMAL` / `INSERT` chip while it is on. No counts, no registers, no undo. `Ctrl+e` still hands the file to the real vim, and that handoff is the answer for anything this mode does not cover. ### mux_open_in `mux_open_in` (issue [#608](https://github.com/kbrdn1/gwm-cli/issues/608)) decides *what* the TUI opens in the multiplexer, for both `t` on the worktree list and `o` on the [agent sessions overlay](/tui/keybindings#agent-sessions-overlay-a). A multiplexer nests panes inside tabs, and herdr nests tabs inside workspaces; this picks the level. | Value | Behaviour | |:------|:----------| | `"pane"` | **Default.** Split the current pane. Which half it takes is [`mux_pane_direction`](#mux_pane_direction) below. | | `"tab"` | A whole screen of its own: a `tmux` **window**, a zellij or herdr **tab**. One thing under three names; the status bar uses your backend's word. | | `"workspace"` | herdr's level above a tab. **herdr only.** | **`"workspace"` is refused on tmux and zellij, not downgraded.** Neither has a level there, so `t` says so on the status bar and opens nothing: ``` tmux has no workspace level: herdr is the only backend with one ``` Quietly opening a tab instead would leave the setting describing something that did not happen, which is worse than a key that refuses and explains itself. The two backends do have *sessions*, which is the structural analogue, but gwm runs inside one: tmux would need two commands to create and switch to a sibling, and zellij refuses to nest sessions at all. Under `"workspace"`, herdr runs `herdr workspace create --label --cwd --focus`. It is `tab create` minus the `--workspace` it would be creating. A `[tui.macro*]` with `open_in = "mux_pane"` reads this key too, and under `"workspace"` it falls back to the PTY overlay on **every** backend: tmux and zellij have no workspace, and herdr's `workspace create` takes no trailing command any more than its `tab create` does. The status bar names which one refused. This key does not reach the CLI. `gwm tmux|zellij|herdr ` spells its own target: bare is a tab, `--split` is a pane. There is no workspace flag, and `--workspace` is taken by the repo-set flag (issue #36). ### mux_pane_direction `mux_pane_direction` (issue [#589](https://github.com/kbrdn1/gwm-cli/issues/589)) decides which half a pane takes, under `mux_open_in = "pane"` and on the CLI's `--split`. Both TUI keys that open one read it: `t` and `o`. | Value | Behaviour | |:------|:----------| | `"right"` | **Default.** Side by side: `tmux split-window -h`, `zellij action new-pane --direction right`, `herdr pane split --direction right`. | | `"down"` | Stacked below: `tmux split-window -v`, `--direction down` on the other two. | | `"left"` | Side by side, other side: `tmux split-window -h -b`, `--direction left` on zellij. **Refused by herdr.** | | `"up"` | Stacked above: `tmux split-window -v -b`, `--direction up` on zellij. **Refused by herdr.** | **`right` is a behaviour change for tmux and zellij users**, and a deliberate one. Up to 1.9 a split carried no direction, so each backend answered for itself: tmux fell back to `-v` and stacked the pane, zellij took "the biggest available space", and herdr went right because gwm hardcoded it there. `right` is what the `--split` help has promised since it shipped ("a horizontal split of the current pane"), and the half that is actually free on a wide screen. Set `mux_pane_direction = "down"` to get the old tmux behaviour back. `-b` is where the second pair comes from, and it is worth knowing before reading tmux's flags as the words suggest: `-h` is the *horizontal split* and puts the pane to the **right**, `-v` stacks it **below**, and `-b` ("before") flips the side on whichever axis was picked. Measured on tmux 3.7c by reading the new pane's geometry back through `split-window -P -F` rather than inferring it from pane order. **`left` and `up` are refused on herdr**, which declares its `--direction` as `[possible values: right, down]` (0.8.2). The status bar says so rather than substituting a direction herdr does have: ``` herdr splits only right or down: left and up are tmux and zellij directions ``` This is [`mux_open_in = "workspace"`](#mux_open_in) inverted: there one backend can do what the other two cannot, here two can do what the third cannot. An unknown value is a **hard config error at load time**, and so is `"window"`, which moved to `mux_open_in = "tab"`. On the CLI, `gwm tmux|zellij|herdr --split` takes its direction from here unless `--direction ` overrides it for that one invocation. ### terminal_browser `terminal_browser` (issue [#590](https://github.com/kbrdn1/gwm-cli/issues/590)) names a command that renders a URL **inside the terminal**, so a link opens next to gwm instead of pulling you out of the workspace gwm is sitting in. It covers every link the TUI opens: the browse-links menu (`B`), the open-menu Issue and PR picks, a row in the rich PR/issue view, a CI check's details URL, and `.` for the docs. ```toml [tui] terminal_browser = "w3m {url}" # or lynx / carbonyl / browsh ``` The `{url}` placeholder is optional. A bare `terminal_browser = "w3m"` gets the URL appended as the last argument, which is what all four of those tools take anyway; `{url}` is for a command that needs it somewhere else (`browser --url={url} --no-sandbox`). **Unset is the default, on every platform, and it is exactly gwm's behaviour up to 1.9**: every link goes to the system browser (`open` / `xdg-open` / `explorer`). Setting the key never removes that path: it adds a rung above it. Where a URL actually lands: | Situation | Where it opens | |:----------|:---------------| | `terminal_browser` unset | System browser. Silently, because the default says nothing about a feature you did not ask for. | | No multiplexer (`$TMUX` / `$ZELLIJ` / `$HERDR_ENV` all unset) | System browser, with the reason in the status bar. | | The browser is not on `$PATH` | System browser, status bar naming the binary. | | `terminal_browser_open_in = "detached"` | The browser is **launched and nothing else**: it places itself. See below. | | A multiplexer whose container takes a command (tmux, a zellij pane) | **A new pane / tab**, running the browser beside gwm. | | A multiplexer whose container takes none (herdr, a zellij tab, any `workspace`) | The **PTY overlay**, with the refusal in the status bar. | **The multiplexer is the gate, deliberately.** A terminal browser with nowhere to put it is worse than the system browser, so gwm does not reach for one outside a multiplexer. The level it opens at is [`mux_open_in`](#mux_open_in) and [`mux_pane_direction`](#mux_pane_direction), the same pair `t` and `o` read, so you do not configure where panes open twice. **herdr and zellij tabs get the overlay rather than a pane.** Neither takes a command in the argv that opens the container ([`mux_open_in`](#mux_open_in) explains the same limit for `o`), and herdr's way around it (open, wait for the new shell's prompt, then type the line) measured up to ~60s on a worktree with `direnv` and a nix flake. For a browser that is the wrong trade: the key was pressed, a page has to appear. The overlay still renders it in the terminal; it covers gwm instead of sitting beside it, which is why the status bar names the backend that refused. #### terminal_browser_open_in Both shapes above host the browser: gwm opens a pane, or falls back to the PTY overlay. That assumes the browser draws inside whatever TTY it is handed, which is true of `w3m`, `lynx` and every other text browser. Some do not. `terminal-browser open {url} --split right` asks the multiplexer for its own pane and exits about four seconds later, and it renders through the terminal's image protocol, which positions against the real window rather than the region it was given. Hosted in the PTY overlay it does not land in the overlay's rect: it paints over the top-left corner of the screen, whatever rect gwm passes, and the mouse hits the same wall. Hosted in a gwm pane it splits twice, once for gwm's pane and once for its own. `terminal_browser_open_in = "detached"` is for those: gwm launches the command and stops there. ```toml [tui] terminal_browser = "terminal-browser open {url} --split right" terminal_browser_open_in = "detached" ``` | Value | Behaviour | |:------|:----------| | `"overlay"` | **Default.** gwm hosts the browser, in a mux pane or the PTY overlay, per the table above. | | `"detached"` | gwm launches the command and nothing else. No pane of its own, no overlay. | **The command has to open its own pane.** `detached` means gwm opens none, so a command that renders in the pane it is given takes over the one gwm is drawing in. `terminal-browser` documents this directly: `open` "opens the browser in the current pane. Pass `--split` to open it in a new split pane instead". Getting this wrong looks exactly like the bug `detached` exists to fix, so check the flag before blaming the mode. **The two gates stay in front of it, and the order is the point.** Placing itself still means asking a multiplexer for a pane, so with none running `terminal-browser open` would take over the pane gwm is drawing in, which is worse than the system browser it falls back to instead. A browser that is not on `$PATH` still falls back too, rather than being launched into nothing. `detached` changes where the browser goes, never whether gwm reaches for one. An unknown value is a **hard config error at load time**, so a typo fails loudly rather than falling back to `overlay` and painting over the screen with no explanation. Also exposed in the Settings panel under the **TUI** tab, next to `terminal_browser`. **The template is an argv, not a shell line.** It is tokenised and executed directly, so a leading `KEY=VAL` assignment is refused rather than run: no shell is there to apply it, and `argv[0]` would be the literal string `NO_COLOR=1`. Write `env NO_COLOR=1 w3m {url}` instead, which works because `env` is a real binary. A `=` inside a later argument is untouched, so `browser --url={url}` is fine. **The URL is one argument, always.** The template is tokenised **before** the placeholder is substituted, so `w3m {url}` and `w3m "{url}"` are the same command and the URL's `?`, `&` and `#` cannot become shell syntax: gwm owns the quoting rather than inheriting whatever the template wrote. Only absolute `http`/`https` URLs are passed on; anything else falls back to the system browser (see the branch-name injection advisory [GHSA-fffq-vg6f-gxqm](https://github.com/kbrdn1/gwm-cli/security/advisories/GHSA-fffq-vg6f-gxqm) for why the order matters). An empty string reads as unset, which is how the Settings panel turns the feature back off. `clipboard` (issue #367) selects how yanked text (path, branch, worktree name, command logs) reaches the clipboard: | Value | Behaviour | |:------|:----------| | `"auto"` | **Default.** OSC52 when `$SSH_TTY` or `$SSH_CONNECTION` is set, host tools otherwise. | | `"osc52"` | Always emit the OSC52 escape sequence. | | `"tools"` | Always use `pbcopy` / `wl-copy` / `xclip` / `xsel` / `clip.exe`. | The host tools write to the clipboard of the machine gwm runs on. Over SSH that is the wrong one, and it fails *silently*: on a remote macOS host `pbcopy` exists, succeeds, and gwm reports `yanked branch name (pbcopy)` while your actual clipboard is untouched. OSC52 hands the text to your terminal emulator, which owns the clipboard you paste from. An unknown value is a **hard config error at load time**. Also exposed in the Settings panel under the **TUI** tab. Three caveats, all rooted in the fact that **OSC52 is never acknowledged**: gwm can report that it emitted the sequence, never that the terminal took it: - **tmux** needs `set -g allow-passthrough on`. gwm wraps the sequence in DCS passthrough, but the option is off by default since tmux 3.3 and gwm cannot detect or enable it. - **GNU screen** (`$STY`) gets the host tools instead: screen needs its own chunked form, and an unwrapped sequence there is silently swallowed. Falling back is the honest failure. - **Terminal support varies**: kitty, WezTerm, Alacritty and iTerm2 (with the setting enabled) honour OSC52; Terminal.app does not. `"tools"` is the escape hatch. It is also the answer for a stale `$SSH_CONNECTION` in a tmux pane, which can make `auto` guess wrong. `auto_refresh_secs` (issue #285) drives a periodic background refresh of the worktree list so the Issue/PR table state stays current without a manual keystroke. It is a non-negative integer count of seconds; the default is `60` and `0` disables the loop. It is also exposed in the Settings panel under the **TUI** tab. See [TUI → Confirm-overlay countdown](/tui/confirm-countdown) and [TUI → Sidebar](/tui/sidebar). ## `[tui.macro1]` and `[tui.macro2]` User-defined commands fired from the worktree list (issue #290). Each is an optional sub-table; when present, the `macro_one` / `macro_two` actions (bound to `h` / `H` by default, see `gwm tui keys`) run the command **in the selected worktree's directory**. When the sub-table is absent the key is a no-op. ```toml [tui.macro1] command = "gh pr view --web" # forwarded to the OS shell (`sh -c`) open_in = "pty" # "pty" (default) | "mux_pane" [tui.macro2] command = "lazygit" open_in = "mux_pane" ``` - `command` (required) is the shell command to execute, forwarded to the OS shell (`sh -c …`). - `open_in` (optional, default `"pty"`) chooses where the command runs: - `"pty"`: an embedded PTY overlay, same as the lazygit / terminal launchers; the TUI suspends until the command exits. - `"mux_pane"`: a new pane of the running multiplexer (tmux via `$TMUX`, or Zellij via `$ZELLIJ`), falling back to a PTY overlay when no multiplexer is detected. The value is `snake_case`, so write `"mux_pane"` (not `"muxpane"`). Both keys are validated at load time; an unknown field under the sub-table errors. ## `[tui.keys.modal.]` Beyond the list-view keymap, the per-modal keymaps are rebindable too (issue #219). Where `[tui.keys]` holds **arrays** for global `View::List` actions (`quit = ["q"]`), the `[tui.keys.modal]` namespace holds **tables**, one per modal context, each binding a context's verbs: ```toml [tui.keys.modal.confirm] confirm = ["y"] cancel = ["n", "Esc"] [tui.keys.modal.help] close = ["Esc", "q", "?"] # Nested contexts use a dotted stage path: [tui.keys.modal.link.choose_target] accept = ["Enter"] cancel = ["Esc"] ``` Each verb takes an array of keys. Unlike the list-view keymap, **modal bindings are single keystrokes**: multi-key chords like `g g` are rejected. An override replaces the verb's default key set; verbs left unmentioned keep their defaults. The `note` context (issue #515) is the narrowest one: the editor is always typing, so every printable plus `Enter`, `Backspace` and `Delete` route to the buffer before any lookup, and only its two exits are bindable. ```toml [tui.keys.modal.note] close = ["Esc"] # writes the buffer and closes open_editor = ["Ctrl+e"] # hands the same file to $EDITOR ``` Binding either of those to a printable, `Enter`, `Backspace` or `Delete` is refused at load time: the key would type instead of firing, leaving the editor with no way out. The set of contexts and verbs is what the TUI actually exposes. Run `gwm tui keys` to print every modal context (`confirm`, `create`, `help`, `command_logs`, `working_tree`, `commits`, `config`, `config.edit`, `report`, `open_menu`, `palette`, `link.choose_target`, `link.input_number`, …) with its verbs and resolved keys. Binding under a context **group** rather than a leaf stage (e.g. `[tui.keys.modal.link]` instead of `[tui.keys.modal.link.choose_target]`) is a load-time error that names the stage to use. Load-time validation rejects, as a hard `GwmError::Config`: an unknown modal context, an unknown verb for a context, an unparsable or multi-stroke key, and a per-context conflict. Note that a handful of names (`create`, `help`, `command_logs`, `working_tree`, `commits`, `link`) exist as both a global action and a modal context. They do **not** collide: the global binding is the array at `tui.keys.`, the modal one is the table at `tui.keys.modal.`, two different paths, and both can live in the same file. What is rejected is putting the modal table at the global path, which names the fix: ```toml [tui.keys] working_tree = ["W"] # global: opens the overlay [tui.keys.modal.working_tree] # modal: its verbs, same name, no conflict close = ["Esc", "q"] ``` ``` tui.keys.working_tree: expected an array of chords; modal contexts go under [tui.keys.modal.], got table ``` See [TUI → Keymap and palette](/tui/keymap-and-palette). ## `[tui.keys]` Configurable keymap (issue #87). Rebind every list-view action with crossterm-grammar keys, including multi-key chords like `g g`. An override **replaces** the default binding for that action; it does not merge. Passing an empty list (`down = []`) unbinds the action entirely. ```toml [tui.keys] down = ["j", "Down"] up = ["k", "Up"] top = ["g g"] bottom = ["G", "End"] quit = ["q"] sync = ["s"] delete_branch = ["D"] toggle_sidebar = ["V"] cycle_sidebar_layout = ["z"] toggle_select = ["Space"] command_palette = [":"] ``` Each value is a list of chord strings. Within a chord string, whitespace separates keystrokes (so `"g g"` is press `g` twice) and `+` separates modifiers from the key (`"Ctrl+x Ctrl+s"`). Use `"Space"` for the literal space character. Recognised modifiers: `Ctrl`, `Alt`, `Shift`. Named keys include `Tab`, `Enter`, `Esc`, `Up`, `Down`, `Left`, `Right`, `Backspace`, `BackTab`, `Home`, `End`, `PageUp`, `PageDown`, `Insert`, `Delete`, `Space`. A shifted letter (`"V"`, `"Shift+v"`) canonicalises to the same uppercase stroke regardless of how the terminal reports shift. ### rebindable actions These are the resolved defaults of the current binary (post-#290 keymap redesign). `gwm tui keys` prints the live list with a per-row source, and stays authoritative if a future build shifts a default. | Action slug | Default chord(s) | Verb | |:--------------------------|:-----------------|:------------------------------------------------------| | `down` | `j`, `Down` | move selection down | | `up` | `k`, `Up` | move selection up | | `top` | `g g` | jump to first row | | `bottom` | `G`, `End` | jump to last row | | `focus_swap` | `Tab` | swap focus between table and sidebar | | `focus_worktrees` | `1` | focus the worktrees pane | | `focus_status` | `2` | focus the status pane | | `command_logs` | `3` | open the Command Logs overlay | | `config_panel` | `4` | open the Settings panel | | `working_tree` | `W` | open the Working Tree listing at full size | | `commits` | `c` | open the commit listing full size, with load-more | | `toggle_sidebar` | `V` | show / hide the details sidebar | | `toggle_sidebar_mode` | `S` | cycle the Details panel (`commits` ↔ `stashes`) | | `cycle_sidebar_layout` | `z` | cycle layout (`auto` → side-by-side → stacked → auto) | | `toggle_sidebar_position` | `v` | flip the sidebar left ↔ right | | `filter` | `/` | open the fuzzy filter bar | | `refresh` | `f` | refresh the worktree list | | `sync` | `s` | fetch + rebase onto upstream (`gwm sync`) | | `create` | `n` | open the new-worktree overlay | | `toggle_select` | `Space` | mark / unmark the row for a bulk delete | | `delete` | `d` | open the delete-confirm overlay (on the marked rows) | | `bootstrap` | `b` | re-run bootstrap on the selected worktree | | `delete_branch` | `D` | arm delete-branch-on-remove | | `pull` | `p` | `git pull` on the selected branch (async) | | `push` | `P` | `git push` on the selected branch (async) | | `edit_worktree` | `e` | rename the worktree / branch | | `edit_note` | `N` | edit the worktree's note in a modal | | `exit_to_worktree` | `E` | quit and print the selected path to stdout | | `lazygit_pty` | `l` | lazygit in the embedded PTY overlay (`[git_tui]`) | | `lazygit_fullscreen` | `L` | lazygit fullscreen | | `review_pty` | `r` | review tool in the PTY overlay (`[review]`) | | `review_fullscreen` | `R` | review tool fullscreen | | `terminal_pty` | `o` | open dispatch in the PTY overlay (`[tui.open]`) | | `terminal_fullscreen` | `O` | open-mode menu / fullscreen terminal | | `yank_path` | `Y` | copy the worktree path | | `yank_branch_name` | `y` | copy the branch name | | `yank_worktree_name` | `w` | copy the worktree name | | `mux_pane` | `t` | open the worktree in a new tmux / zellij / herdr pane | | `macro_one` | `h` | run `[tui.macro1]` | | `macro_two` | `H` | run `[tui.macro2]` | | `browse_links` | `B` | browse the issue / PR links | | `open_docs` | `.` | open the docs in the browser | | `link` | `i` | open the issue/PR link prompt | | `fetch_github` | `F` | fetch GitHub issue/PR state | | `help` | `?` | toggle the help overlay | | `quit` | `q` | quit the TUI | | `command_palette` | `:` | open the command palette | `Ctrl+C` (emergency quit) and the contextual `Esc` / `Enter` keys are hard-coded escape hatches outside the keymap, and they keep working regardless of `[tui.keys]`. **Load-time validation** rejects, as a hard `GwmError::Config`: - an **unknown action** slug (the error points you at `gwm tui keys` for the full list); - a **parse error** in a chord string (empty, dangling `+`, unknown modifier, unknown key name); - a **chord conflict**: two actions bound to the same chord; - a **prefix collision**: a chord that is a strict prefix of another bound chord (e.g. binding `g` alone while `g g` is also bound). Resolving this at runtime would need a Vim-style timeout in the event loop, so gwm refuses the config instead. `gwm tui keys` prints the resolved keymap with a per-row source; `gwm doctor` warns when no non-`Ctrl+C` binding for `quit` survives the overrides. The help overlay (`?`) is keymap-driven, so the documentation always matches the resolved bindings. See [TUI → Keymap and palette](/tui/keymap-and-palette). ## `[tui.open]` What the `o` key does. Full details in [TUI → Open dispatch](/tui/open-dispatch). ```toml [tui.open] mode = "shell" # shell (default) | editor | finder shell_cmd = "" # override $SHELL when mode=shell; empty = unset editor_cmd = "hx" # override $EDITOR when mode=editor; empty = unset ``` Unknown `mode` values are a **hard config error at load time**, not a silent fallback. ## `[tui.agent_resume]` How `o` on the [agent sessions overlay](/tui/keybindings#agent-sessions-overlay-a) resumes each backend in the new multiplexer pane (issue [#591](https://github.com/kbrdn1/gwm-cli/issues/591)). ```toml [tui.agent_resume] claude = "claude -r {session}" # Claude Code codex = "codex resume {session}" # Codex opencode = "opencode -s {session}" # opencode vibe = "vibe --resume {session}" # Mistral Vibe ``` Those are the defaults, so an absent block resumes all four correctly and no `.gwm.toml` change is required. They are configuration rather than a hardcoded table because these are four third-party CLIs on their own release cadence: the day one of them renames its flag, a gwm release should not be what stands between you and a working `o`. `{session}` is the detected session id, substituted in a single pass. It is read out of the tool's own artefacts on disk, so it is **data**: gwm refuses to resume unless it is a plain id (ASCII letters, digits, `-`, `_`, `.`), and quotes it on top. The charset is the load-bearing half, because the template around the placeholder is yours: write `claude -r "{session}"` and quoting alone would leave a `$(…)` in the id live, since the quotes it adds are literal inside your double quotes. Every real id is a UUID or a slug, so nothing legitimate is refused. An empty string on a key reads as unset and gives the default back, the convention `shell_cmd` / `editor_cmd` already use. The **level** the pane opens at is not set here: `o` reads [`mux_open_in`](#mux_open_in) and [`mux_pane_direction`](#mux_pane_direction) like `t` does. That is also where its refusals come from, since not every level can carry a command: a zellij tab takes none, and neither herdr level does. ## `[theme]` Role-based TUI colours (issue #33). Every visual signal maps to a semantic role rather than a hard-coded colour, so a `[theme]` block re-skins the whole TUI. Two knobs: an optional `preset` (a built-in palette) and any number of per-role overrides on top of it. ```toml [theme] preset = "catppuccin" # optional — seed every role from a built-in palette focus = "#89b4fa" # per-role override on top of the preset accent = "mauve" # (illustrative — named colours below) ``` `preset` (optional) seeds every role from a built-in palette; when absent, gwm starts from the default scheme (the pre-#33 hardcoded look). Built-in presets: | Preset | Alias(es) | |:--------------|:--------------------------------| | `catppuccin` | `catppuccin-mocha` | | `gruvbox` | `gruvbox-dark` | | `tokyo-night` | `tokyonight` | | `claude-dark` | `claude` | `gwm theme list` prints the preset names; `gwm theme show ` dumps a preset as a copy-pasteable, round-trippable `[theme]` block. ### roles Override any of these keys individually: a per-role override **wins over the preset** (and over the default). The override is applied on top of whichever base `preset` selects. | Role | Used for | Default | |:---------------|:--------------------------------------------------------|:--------------| | `focus` | focused border / cursor / active overlay highlight | `cyan` | | `accent` | header title, help-overlay key hints, palette prompt | `cyan` | | `branch` | branch name in lists and the sidebar identity card | `green` | | `clean` | "working tree is clean" status indicator | `green` | | `dirty` | "working tree is dirty" status indicator | `yellow` | | `main` | main / trunk worktree badge | `yellow` | | `locked` | locked worktree badge (`🔒`) | `magenta` | | `prunable` | prunable worktree badge (`⚠`) | `red` | | `muted` | de-emphasised text: hints, footers, placeholders | `dark_gray` | | `selection_bg` | selection highlight background | `dark_gray` | | `name` | worktree name + `Issue #N` / `PR #N` summary heads | `white` | | `path` | worktree path column in the table | `gray` | | `staged` | staged (index-side) git-status changes | `cyan` | | `modified` | worktree-side git-status modifications | `yellow` | | `untracked` | untracked / created git-status entries (`??`) | `green` | | `section_bg` | compact-mode section header fill (`[tui] layout`) | `236` | ### colour value formats Each role accepts a colour in one of three forms: - **Named**: `cyan`, `Cyan`, `dark_gray`, `bright_blue` (case-insensitive). - **256-palette index**: `0`..=`255` (e.g. `220`). - **Hex**: `#RRGGBB` (six hex digits + leading `#`, e.g. `#89b4fa`). Short `#RGB` form is **not** supported; the parser refuses to guess. **Validation runs at load** (issue #33): an unknown `preset`, an unknown role key, or an unparsable colour value are each a hard `GwmError::Config`, attributed to the offending `theme.` coordinate. Users who omit `[theme]` see the unchanged default scheme. See [TUI → Themes](/tui/themes). ## `[doctor]` Knobs for `gwm doctor`. Currently exposes the trunk list used by the orphan-branch check. ```toml [doctor] # Branches the orphan check treats as "merge destinations". A gwm-style # branch fully reachable from one of these is preserved per CONTRIBUTING # ("never delete the source branch after merge") and NOT flagged as orphan. # Empty list → every unclaimed gwm-style branch is flagged. trunks = ["dev", "main"] ``` Repos using a non-default trunk (`master`, `trunk`, `release-1.x`, …) must list it here to keep the orphan check meaningful. ## `[gitmoji]` (issue #85) Per-repo override of the built-in `branch_type → :shortcode:` table consumed by [`gwm commit-prefix`](/cli/reference#gwm-commit-prefix---branch-name---unicode), [`gwm types --gitmoji`](/cli/reference#gwm-types---gitmoji), and the bundled commit-msg hook ([`gwm hooks install commit-msg`](/cli/reference#gwm-hooks-install-commit-msg---force)). ```toml [gitmoji] feat = ":rocket:" # team uses 🚀 for new features instead of ✨ migration = ":truck:" # custom branch type ``` Defaults (used when `[gitmoji]` is absent or omits a key): | branch type | shortcode | unicode | |:------------|:------------------------|:--------| | `feat` | `:sparkles:` | ✨ | | `fix` | `:bug:` | 🐛 | | `hotfix` | `:ambulance:` | 🚑 | | `docs` | `:memo:` | 📝 | | `test` | `:white_check_mark:` | ✅ | | `refactor` | `:recycle:` | ♻ | | `chore` | `:wrench:` | 🔧 | | `perf` | `:zap:` | ⚡ | | `ci` | `:construction_worker:` | 👷 | | `build` | `:package:` | 📦 | `[gitmoji]` is **additive**: overriding one entry doesn't wipe the other nine. Custom branch types declared under `[[branch_types]]` can carry their own emoji here without redeclaring the built-ins. ### `--unicode` normalisation of overrides Surfaces that render the prefix as a unicode glyph (`gwm commit-prefix --unicode`, the unicode column of `gwm types --gitmoji`, and the installed commit-msg hook) **normalise known `:shortcode:` overrides to their glyph**: ```toml [gitmoji] feat = ":rocket:" ``` ```text $ gwm commit-prefix --branch feat/#1-x :rocket: feat(#1): $ gwm commit-prefix --branch feat/#1-x --unicode 🚀 feat(#1): ``` The known-shortcode set covers the ten built-in mappings plus a curated extension of the most commonly-swapped Gitmoji entries (`:rocket:`, `:fire:`, `:lock:`, `:art:`, `:lipstick:`, `:hammer:`, `:bookmark:`, …). **Unknown shortcodes fall through verbatim**: no panic, no substitution: ```toml [gitmoji] feat = ":foo:" # not in the built-in unicode table ``` ```text $ gwm commit-prefix --branch feat/#1-x --unicode :foo: feat(#1): ``` Without `--unicode`, every override is emitted verbatim regardless of whether the table knows it: the shortcode form is the one downstream consumers (GitHub Markdown, commit linters, gitmoji-cli) parse. ## `[[labels]]` (issue #81) Declarative GitHub label set pushed to the `origin` remote by [`gwm labels push`](/cli/reference#gwm-labels-listpush). ```toml [[labels]] name = "bug" description = "Something isn't working" color = "d73a4a" # optional — deterministic pastel if omitted [[labels]] name = "enhancement" description = "New feature or request" [[labels]] name = "good first issue" description = "Good for newcomers" color = "7057ff" ``` | Field | Type | Required | Meaning | |:--------------|:-------|:---------|:----------------------------------------------------------------------------------------------| | `name` | string | yes | GitHub label name. Whitespace preserved verbatim, so quote it: `name = "good first issue"`. | | `description` | string | no | Empty / absent means "don't change the description on the remote". | | `color` | string | no | 6-hex lowercase, no leading `#` (`#D73A4A` is accepted and normalised). When omitted, gwm derives a deterministic pastel from an FNV-1a hash of `name` so the same label gets the same colour across repos. | Resolution order: 1. **Declared `color`** in `.gwm.toml` wins. 2. **Deterministic pastel** from a hash of the name when `color` is omitted (default). 3. **Random pastel** when the user passes `gwm labels push --random-colors`. Workflow: - `gwm labels list`: print the resolved set plus the diff against the remote (`+ create`, `~ update`, `= match`, `- extra-on-remote`). - `gwm labels push`: apply create + update. - `gwm labels push --dry-run`: plan only, no remote mutations. Still reads remote labels via `gh label list` to compute the diff; only create / update / delete calls are skipped. - `gwm labels push --prune`: also delete labels on the remote that aren't declared in config (destructive, opt-in). Without a `[[labels]]` block, `gwm labels {list|push}` are no-ops (`0 labels declared, nothing to push`) and never shell out to `gh`. Requires `gh` on `$PATH` once labels are declared (the same soft dependency as `gwm status`). ## `[[milestones]]` (issue #82) Declarative GitHub milestone set pushed to the `origin` remote by [`gwm milestones push`](/cli/reference#gwm-milestones-listpush). Mirrors the `[[labels]]` shape; the REST endpoint is used because `gh` has no native `gh milestone` subcommand. ```toml [[milestones]] title = "v0.7.0" description = "Configurability sprint" due_on = "2026-07-15" # YYYY-MM-DD → end-of-day UTC state = "open" # default "open", or "closed" [[milestones]] title = "v0.8.0" due_on = "2026-10-01T17:00:00Z" # full RFC3339 also accepted [[milestones]] title = "v0.6.0" state = "closed" # archive declaratively ``` | Field | Type | Required | Meaning | |:--------------|:-------|:---------|:---------------------------------------------------------------------------------------------------------------------------------| | `title` | string | yes | GitHub milestone title (unique per repo). Whitespace preserved verbatim. | | `description` | string | no | Empty / absent means "don't change the description on the remote". | | `due_on` | string | no | `YYYY-MM-DD` (materialised as 23:59:59 UTC of that day, common-sense "due Friday" semantic) or full RFC3339 (`2026-07-15T17:00:00Z`). Absent means no due date. | | `state` | string | no | `"open"` (default) or `"closed"`. Use `"closed"` to archive a milestone declaratively. | Workflow: - `gwm milestones list`: print the resolved set plus the diff against the remote (`+ create`, `~ update`, `= match`, `- extra-on-remote`). - `gwm milestones push`: apply create + update. - `gwm milestones push --dry-run`: plan only, no remote mutations. Still reads remote milestones via `gh api` to compute the diff; only create / update / delete calls are skipped. - `gwm milestones push --prune`: also delete milestones on the remote that aren't declared in config (destructive, opt-in). Without a `[[milestones]]` block, `gwm milestones {list|push}` are no-ops (`0 milestones declared, nothing to push`) and never shell out to `gh`. Requires `gh` on `$PATH` once milestones are declared (the same soft dependency as `gwm labels` / `gwm status`). ## `[issue_template]` (issue #83) Per-branch-type defaults for `gwm new `. The command renders a GitHub issue-form YAML file from `.github/ISSUE_TEMPLATE/`, creates the issue with `gh issue create`, then creates the worktree using the returned issue number. ```toml [issue_template] default = "feature_request.yml" [issue_template.by_type] feat = { template = "feature_request.yml", surface = "cli", title_prefix = "[Feature]: ", labels = ["enhancement"] } fix = { template = "bug_report.yml", surface = "cli", title_prefix = "[Bug]: " } docs = { template = "task.yml", title_prefix = "[Docs]: " } hotfix = { template = "bug_report.yml", surface = "cli", title_prefix = "[Hotfix]: ", labels = ["priority: high"] } ``` | Field | Type | Meaning | |:---------------|:----------------|:------------------------------------------------------------------------| | `default` | string | fallback file under `.github/ISSUE_TEMPLATE/` | | `template` | string | per-type template override | | `surface` | string | default value for a form field with `id: surface` | | `title_prefix` | string | overrides the issue-form `title:` prefix | | `labels` | list of strings | extra labels appended to labels declared by the issue-form YAML | `labels` is read in both directions since [#617](https://github.com/kbrdn1/gwm-cli/issues/617): `gwm new` writes them onto the issue it creates, and `gwm create --issue ` reads the map backwards to derive the branch type from an issue that already exists. A type that declares no labels is never derivable, and labels that select two types make `gwm create --issue` refuse until `--type` picks one, so it is worth giving each type a label no other type carries. `title_prefix` is symmetric the same way: `gwm create --issue` takes back off exactly what `gwm new` put on, falling back to the issue form's own `title:` when the config sets none. Template bodies support placeholders `{type}`, `{desc}`, and `{repo}`. Issue-form markdown blocks are preserved, text inputs/areas become markdown sections, and configured dropdown defaults render as single-line `**Label:** value` entries. ## `[pr_template]` (issue #84) Per-branch-type PR bodies for `gwm pr [--draft] [--base ] [--render]`. Without the subcommand, `gh pr create` falls back to `.github/pull_request_template.md`; `gwm pr` lets each branch type point at its own body so a `docs/` PR doesn't get the same checklist as a `hotfix/`. ```toml [pr_template] default = ".github/pull_request_template.md" [pr_template.by_type] feat = { path = ".github/pr-templates/feat.md" } fix = { path = ".github/pr-templates/fix.md" } docs = { path = ".github/pr-templates/docs.md" } [pr_template.by_type.chore] body = """ ## Summary {desc} Closes #{issue} ## Test plan - [ ] cargo test """ ``` | Field | Type | Meaning | |:----------|:-------|:-------------------------------------------------------------------------| | `default` | string | fallback Markdown file (workdir-relative path) | | `path` | string | per-type Markdown file (workdir-relative path) | | `body` | string | inline Markdown body, wins over `path` when both are set on one type | Both `default` and `path` are workdir-relative paths; absolute paths, `..` parents, and Windows drive prefixes are rejected to stop a template path from escaping the worktree root. Placeholders the renderer substitutes before handing the body to `gh pr create`: | Placeholder | Source | |:------------------|:------------------------------------------------------------------------------| | `{type}` | branch type parsed from the current branch name | | `{issue}` | issue number parsed from the branch name (empty when none) | | `{desc}` | description slug parsed from the branch name | | `{base}` | resolved trunk from `[doctor].trunks` (first that exists) or `--base` value | | `{head}` | current branch shorthand | | `{repo}` | `owner/repo` slug parsed from the `origin` remote URL | | `{commits}` | `git log --pretty=format:- %s {base}..{head}` (one bullet per commit subject) | | `{files_changed}` | `git diff --stat {base}..{head}`, capped at 30 lines (`… N more lines trimmed`) | `gwm pr --render` prints the rendered body to stdout instead of creating a PR, which is useful for `gwm pr --render | gh pr create --body-file -` when you want to tweak the body in `$EDITOR` first. ## `[aliases]` (issue #86) Repo-level CLI aliases: declarative `git config`-style aliases that follow the repo across machines. Each entry maps an alias name to an argv-substituted expansion run BEFORE clap parses, so `wip = "create feat 0 wip"` makes `gwm wip` behave as `gwm create feat 0 wip`. ```toml [aliases] wip = "create feat 0 wip" ll = "list --format names" sync = "bootstrap" ``` A user-level fallback lives at `~/.config/gwm/aliases.toml` (resolved like the [global config](/configuration/global-config#location): `$XDG_CONFIG_HOME` wins outright, otherwise the first existing of `~/.config` then the platform dir, issue #374); same `[aliases]` block shape. Repo aliases win over user aliases on name collision. Surface the resolved chain with `gwm aliases list`. See [CLI → `gwm aliases list`](/cli/reference#gwm-aliases-list-issue-86) for the rendered output and the per-source flagging. **Rules enforced at load time** (`Config::load_for_repo` returns `GwmError::Config` on violation): | Rule | Reason | |:-------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------| | Alias name MUST NOT shadow a built-in subcommand (`list`, `switch`, …) | Built-in subcommands are the strongest binding, and silent shadowing is a bug factory. | | Alias name MUST NOT shadow a built-in visible alias (`s`, `cd`) | Same reasoning: `gwm s` should always reach `switch`. | | Alias value MUST NOT be empty | Nothing to expand to. | | Alias value MUST NOT contain shell metachars (`&&`, `\|\|`, `\|`, `;`, backticks) | Aliases are argv substitution only, so use a shell alias for shell semantics. | Single-pass expansion: `wip = "ll"` followed by `ll = "list --format names"` expands ONCE and then dispatches; the second hop is not resolved. ## defaults without `.gwm.toml` | Setting | Default | |:-------------------------------------|:---------------------------------| | `[worktree].base` | `{home}/cc-worktree/{repo}` | | `[worktree].path_pattern` | `{type}-{issue}-{desc}` | | `[worktree].branch_pattern` | `{type}/#{issue}-{desc}` | | `[[bootstrap.*]]` | empty, no pipeline | | `[git_tui].command` | `lazygit -p {path}` | | `[git_tui].fullscreen` | `true` | | `[review]` | inert (`R` does nothing) | | `[tui].confirm_countdown_secs` | `3` | | `[tui].sidebar_position` | `right` | | `[tui].sidebar_orientation` | `stacked` | | `[tui].layout` | `compact` | | `[tui].dim_unfocused` | `false` | | `[tui].status_one_line` | `true` | | `[tui].note_vim` | `true` | | `[tui].mux_open_in` | `pane` | | `[tui].mux_pane_direction` | `right` | | `[tui].terminal_browser` | unset (system browser) | | `[tui].terminal_browser_open_in` | `overlay` (gwm hosts it) | | `[tui].clipboard` | `auto` | | `[tui].auto_refresh_secs` | `60` (`0` disables) | | `[tui.macro1]` / `[tui.macro2]` | absent, `h` / `H` are no-ops | | `[tui.keys]` | built-in keymap (see table above) | | `[tui.keys.modal.*]` | built-in modal keymaps (`gwm tui keys`) | | `[tui.open].mode` | `shell` (v0.6, was `finder`) | | `[theme].preset` | none, default hardcoded scheme | | `[doctor].trunks` | `["dev", "main"]` | | `[[labels]]` | empty, `gwm labels {list,push}` are no-ops | | `[issue_template]` | empty, `gwm new` is not configured | | `[pr_template]` | empty, `gwm pr` errors with a hint, `gh pr create` keeps using `.github/pull_request_template.md` | | `[aliases]` | empty, no CLI alias expansion | ## validation rules - Unknown TOML keys are a **hard load error**: the root `[Config]` table and nearly every sub-table (`[worktree]`, `[bootstrap]`, `[hooks]`, `[doctor]`, `[tui]`, `[tui.open]`, `[git_tui]`, `[review]`, `[[labels]]`, `[[milestones]]`, `[[branch_types]]`, `[issue_template]`, `[pr_template]`) reject fields they don't recognise. A stray top-level key (or an unknown key inside a deny-fields table) fails the load with a `Config` error rather than being ignored. The same check runs on the merged result, so a typo in the global `~/.config/gwm/config.toml` fails just as hard. Exceptions: `[theme]` flattens per-role overrides (arbitrary role-named keys are accepted, then validated against the known role set, see below), and `[gitmoji]` / `[aliases]` are open key→value maps. - Unknown `[tui.open].mode`, `[tui].sidebar_position`, `[tui].sidebar_orientation`, `[tui].layout`, `[tui].clipboard` and `[tui].terminal_browser_open_in` values **error at load time**. - `[theme]` errors at load on an unknown `preset`, unknown role key, or unparsable colour value. - `[tui.keys]` errors at load on an unknown action, an unparsable chord, a chord conflict, or a prefix collision. - `[tui.keys.modal.*]` errors at load on an unknown context, an unknown verb, an unparsable or multi-stroke key, binding under a context group instead of a leaf stage, or a per-context conflict. - `[tui.macro1]` / `[tui.macro2]` error at load on an unknown field; `open_in` accepts only `"pty"` or `"mux_pane"`. - `[aliases]` names that shadow a built-in subcommand / visible alias, are empty, or contain shell metachars **error at load time**. - `[[bootstrap.guard]]` references in `[[bootstrap.copy]].guards` are validated by `gwm doctor` (check #2). - `[[bootstrap.command]].when` predicates with unknown keywords default to `true` (so old configs keep running); `gwm doctor` (check #3) surfaces them. Run `gwm doctor` after every edit to catch the catchable mistakes. See [Integrations → `gwm doctor`](/integrations/doctor).