---
title: Configuration
description: The .gwm.toml schema, covering worktree conventions, bootstrap pipeline, lifecycle hooks, regex guards, when-predicates, theme, keymap, templates, aliases, and the user-level global config.
navigation:
  title: Configuration
---

# Configuration

gwm reads `.gwm.toml` from the repo root. Without a config, it falls back to sensible defaults (`~/cc-worktree/<repo>/<type>-<issue>-<desc>`, no bootstrap). With one, it can copy files, run lifecycle hooks, refuse to inherit dangerous secrets, configure the TUI launchers / keymap / theme, and declare GitHub labels, milestones, and issue / PR templates. The same schema can also live at a [user-level global config](/configuration/global-config) merged underneath every repo.

- **[`.gwm.toml` schema](/configuration/gwm-toml)**: every section, from `[worktree]`, `[[bootstrap.copy]]`, `[[bootstrap.guard]]`, `[bootstrap.fallback.*]`, `[[bootstrap.no_symlink]]`, `[[hooks.*]]` (+ legacy `[[bootstrap.command]]`), `[theme]`, `[tui]`, `[tui.keys]`, `[tui.open]`, `[git_tui]`, `[review]`, `[gitmoji]`, `[[labels]]`, `[[milestones]]`, `[issue_template]`, `[pr_template]`, `[aliases]`, `[doctor]`.
- **[User-level global config](/configuration/global-config)**: `~/.config/gwm/config.toml` merged underneath each repo's `.gwm.toml`; deep-overlay semantics and the `GWM_NO_GLOBAL_CONFIG=1` opt-out.
- **[Bootstrap pipeline](/configuration/bootstrap)**: execution order, with lifecycle hooks around copies → guards → fallbacks → no-symlink check.
- **[Regex guards](/configuration/guards)**: deny-list patterns on copied files (the original "no AWS RDS in `.env`" incident).
- **[`when` predicates](/configuration/when-predicates)**: `file_exists:`, `cmd_exists:`, `env_set:`, `env_eq:`, `glob_exists:`, with `!`, `&&`, `||` composition.
- **[TOFU trust ledger](/configuration/trust-ledger)**: the gate that fires before the bootstrap pipeline (issue #95). Threat model, CLI surface (`gwm trust list / revoke / show`), TUI behaviour, ledger format, CI bypass.
- **[Config presets](/configuration/presets)**: `gwm init --preset <stack>` seeds an opinionated `.gwm.toml` for a known stack (`laravel`, `symfony`, `node`/`nuxt`, `rust`, `go`, `python-uv`, `generic`) instead of the generic template; `--list-presets` and `--show`.

Run `gwm init` in a fresh repo to write a default `.gwm.toml`. For the full annotated example with every field commented, see [`examples/gwm.toml.example`](https://github.com/kbrdn1/gwm-cli/blob/main/examples/gwm.toml.example) in the repo.