Configuration Management - Comprehensive Guide

This guide teaches you how to configure gw for optimal workflows across different project types.

Table of Contents

1. Understanding gw Configuration
2. Configuration Options Reference
3. Auto-Copy Strategies
4. Project-Type Configuration Patterns
5. Team Configuration Management
6. Advanced Configuration Techniques
7. Troubleshooting Configuration

---

1. Understanding gw Configuration

Config File Location

gw stores configuration at .gw/config.json in your repository:

/projects/myapp.git/
├── main/                  # Main worktree
│   ├── src/
│   ├── .gw/
│   │   └── config.json   # ← Configuration file
│   └── package.json
├── feature-a/             # Other worktrees
└── feature-b/

Auto-Detection vs Manual Configuration

Auto-detection (recommended for most cases):

$ cd /projects/myapp/main
$ gw init

Repository root detected: /projects/myapp.git
Default branch detected: main
Configuration created at .gw/config.json

gw automatically detects:

• Repository root (parent directory containing worktrees)
• Default branch (main, master, or current branch)

Manual configuration (when auto-detection fails):

$ gw init --root /projects/myapp.git \
          --default-branch main \
          --auto-copy-files .env,.env.local,secrets/

Configuration Scope

Configuration is per-repository, not global:

• Each repository has its own .gw/config.json
• Different repos can have different configurations
• Configuration is shared across all worktrees in that repo

Config Precedence and Defaults

If no configuration exists:

1. gw searches for .gw/config.json walking up from current directory
2. If not found, attempts auto-detection on first gw add command
3. Uses fallback defaults:
   • root: Auto-detected from git worktree list
   • defaultBranch: "main"
   • autoCopyFiles: [] (nothing copied automatically)

---

2. Configuration Options Reference

Complete Configuration Structure

{
  "root": "/absolute/path/to/repo.git",
  "defaultBranch": "main",
  "autoCopyFiles": [
    ".env",
    ".env.local",
    "secrets/",
    "config/local.json"
  ],
  "cleanThreshold": 7
}

root: Repository Root Path

Purpose: Absolute path to the parent directory containing all worktrees.

Example:

{
  "root": "/Users/you/projects/myapp.git"
}

How it's used:

• Resolving worktree names to absolute paths
• Finding source files for auto-copy
• Determining worktree relationships

When to set manually:

• Auto-detection fails (unusual directory structure)
• Repository has non-standard naming
• Using symlinks or network drives

defaultBranch: Default Source Worktree

Purpose: Which worktree to copy files from by default.

Example:

{
  "defaultBranch": "develop"
}

Common values:

• "main" - Most projects
• "master" - Older projects
• "develop" - Gitflow workflow
• "staging" - Copy from staging environment

How it's used:

• gw add feature-x copies from defaultBranch worktree
• gw sync target file.txt syncs from defaultBranch unless --from specified
• gw sync target (without files) syncs autoCopyFiles from defaultBranch

autoCopyFiles: File Patterns to Auto-Copy

Purpose: Files/directories automatically copied when creating worktrees.

Example:

{
  "autoCopyFiles": [
    ".env",
    ".env.local",
    "secrets/api-keys.json",
    "config/",
    "ssl/"
  ]
}

Pattern types:

1. Exact files: ".env" - Single file
2. Directories: "secrets/" - Entire directory (recursive)
3. Nested paths: "config/local.json" - Specific nested file

How it's used:

• gw add feature-x automatically copies these files when creating worktrees
• gw sync feature-x (without file arguments) syncs these files to existing worktrees

Important notes:

• Paths are relative to repository root
• Directories should end with /
• Files are copied, not symlinked
• Non-existent files are skipped with warning

cleanThreshold: Worktree Cleanup Age

Purpose: Number of days before worktrees are considered stale for gw clean.

Example:

{
  "cleanThreshold": 7
}

Common values:

• 7 - Default (one week)
• 14 - Two weeks (more lenient)
• 3 - Three days (aggressive cleanup)
• 30 - One month (very lenient)

How it's used:

• gw clean removes worktrees older than this threshold
• Only removes worktrees with no uncommitted changes and no unpushed commits (unless --force)
• gw clean --dry-run previews which worktrees would be removed

Setting the threshold:

# Set during initializat

...