gw Configuration Management

Config lives at .gw/config.json (committable) and .gw/config.local.json (gitignored, personal overrides). All worktrees in a repo share the same config.

MANDATORY: Config-Change Rules

Non-negotiable in any gw-tools repo.

The canonical migration guide is in the project root CLAUDE.md under "Config Migration System". See also packages/gw-tool/src/lib/config-migrations.ts (current version: CURRENTCONFIGVERSION = 2).

Rules

Complete Config Reference

{
  // Added automatically by gw init — enables IDE autocompletion/validation
  "$schema": "https://raw.githubusercontent.com/mthines/gw-tools/main/packages/gw-tool/schemas/gw-config.schema.json",

  // Managed automatically — do not edit manually
  "configVersion": 3,

  // Branch whose worktree is the source for auto-copy and sync (default: "main")
  // This worktree is protected from auto-clean.
  "defaultBranch": "main",

  // Files/dirs copied from defaultBranch worktree when gw checkout runs.
  // Paths are relative to repo root. Directories end with /. Non-existent entries are skipped with a warning.
  "autoCopyFiles": [".env", ".env.local", "secrets/"],

  // Commands run before/after gw checkout. Supports variable substitution (see Hooks below).
  "hooks": {
    "checkout": {
      // Pre-hooks: run before worktree creation. Failure aborts the checkout.
      "pre": ["echo 'Creating: {worktree}'"],
      // Post-hooks: run after successful creation. Failure warns but does NOT roll back.
      "post": ["cd {worktreePath} && pnpm install"],
    },
  },

  // Days before worktrees are considered stale for gw clean / auto-clean (default: 7)
  "cleanThreshold": 7,

  // When true, silently prunes stale worktrees after gw checkout / gw list.
  // Never removes defaultBranch. Only removes worktrees with no uncommitted or unpushed changes. (default: false)
  "autoClean": false,

  // Default strategy for gw update: "merge" (preserves history) or "rebase" (linear). (default: "merge")
  // Override per-command with --merge or --rebase flags.
  "updateStrategy": "merge",

  // Extra branch names to protect from gw clean and auto-clean.
  // Managed with 'gw protect' / 'gw unprotect'. defaultBranch, main, master,
  // and gw_root are always protected regardless of this list. (default: [])
  "protectedBranches": ["staging", "release/v2"],
}

Local overrides — create .gw/config.local.json to override any field for your machine only. It is gitignored automatically and shallow-merged on top of config.json (local wins).

Hook Variables

Available for substitution in any hook command string:

Example using variables:

{
  "hooks": {
    "checkout": {
      "post": ["cd {worktreePath} && pnpm install", "echo 'Ready at {worktreePath}'"],
    },
  },
}

Adding a Migration (required when changing Config)

When any field in packages/gw-tool/src/lib/types.ts's Config interface is added, renamed, or removed, follow this checklist — see root CLAUDE.md for the full authoritative process:

1. Increment CURRENTCONFIGVERSION in config-migrations.ts
2. Add a migration entry to the MIGRATIONS array that transforms old configs and sets config.configVersion = <new version>
3. Update types.ts to reflect the new shape
4. Update schemas/gw-config.schema.json — add/remove/rename properties, update "default" on configVersion to the new version
5. Remove any command-level backcompat code — migrations own backwards compatibility

Migration skeleton:

{
  version: 3, // next version number
  description: 'Rename oldField to newField',
  migrate: (config) => {
    if (config.oldField !== undefined) {
      config.newField = config.oldField;
      delete config.oldField;
    }
    config.configVersion = 3;
    return config;
  },
}

Quick Command Reference

Anti-Patterns

Key Principles

• Set up secrets in defaultBranch first — source must exist before auto-copy works.
• Commit config.json to version control — team members get it automatically.
• Copy secrets, not dependencies — .env yes, node_modules/ no.
• Migrations own backwards compat — never add shims in command code.
• gw show-init documents your setup — generates a shareable init command from current config.

Related Skills

• [git-worktree-workflows](../git-worktree-workflows/) - Using worktrees effectively (gw checkout, gw cd, gw clean, etc.)
• autonomous-workflow - Autonomous development in isolated worktrees (lives in mthines/agent-skills)

Resources

• [Project-Type Guides](./rules/project-types/) - Configuration guides for Next.js, Node.js API, monorepo, React SPA
• [Next.js Setup Example](./references/nextjs-setup.md)
• [Monorepo Setup Example](./references/monorepo-setup.md)
• [Troubleshooting Guide](./references/troubleshooting-config.md)