config-management（配置管理）

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. Initial Setup: Secrets in the Default Branch
4. Auto-Copy Strategies
5. Project-Type Configuration Patterns
6. Team Configuration Management
7. Advanced Configuration Techniques
8. 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/

Interactive configuration (for guided setup):

$ gw init --interactive

Interactive Configuration

Press Enter to accept defaults. Leave blank to skip optional settings.

Default source worktree name [main]: main
Do you want to auto-copy files when creating worktrees? (y/n) [n]: y
  Enter comma-separated file/directory paths (e.g., .env,secrets/)
  Files to auto-copy: .env,.env.local,secrets/
Do you want to add post-add hooks? (y/n) [n]: y
  Enter commands to run after creating worktrees
  Variables: {worktree}, {worktreePath}, {gitRoot}, {branch}
  Post-add hook 1 (leave blank to finish): pnpm install
  Post-add hook 2 (leave blank to finish):
Days before worktrees are considered stale [7]: 14
Enable automatic cleanup of stale worktrees? (y/n) [n]: n

✓ Configuration created successfully

Interactive mode is useful when:

• Setting up gw for the first time
• You're unsure about configuration options
• You want to explore all available settings
• Onboarding new team members who need guidance

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
• Auto-clean never removes this worktree - it's protected as the source for file syncing

Important: Ensure your secrets and environment files exist in the defaultBranch worktree before using gw add or gw sync. This worktree is the source from which files are copied.

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 initialization
gw init --clean-threshold 14

# Or manually edit .gw/config.json

Important notes:

• Age is calculated from the worktree's .git file modification time
• Bare/main repository worktrees are never removed
• Use --force flag to bypass safety checks (not recommended)

3. Initial Setup: Secrets in the Default Branch

Before using gw add with auto-copy, your secrets and environment files must exist in your defaultBranch worktree. This worktree is the source from which files are copied.

First-Time Setup Flow

# 1. Set up your bare repository structure
git clone --bare https://github.com/user/repo.git repo.git
cd repo.git

# 2. Create the main worktree (your defaultBranch)
git worktree add main main

# 3. Set up secrets in the main worktree FIRST
cd main
cp .env.example .env           # Create your environment file
# Edit .env with your actual secrets, API keys, etc.
mkdir -p secrets/
# Add any other secret files your project needs

# 4. Initialize gw with auto-copy configuration
gw init --auto-copy-files .env,secrets/

# 5. Now create feature worktrees - files are copied automatically
cd ..
gw add feat-new-feature
# .env and secrets/ are automatically copied from main

Why This Order Matters

1. Source must exist first - gw add copies from defaultBranch, so files must be there
2. Auto-clean protection - The defaultBranch worktree is never auto-cleaned, ensuring your source files are always available
3. Sync depends on source - gw sync also uses defaultBranch as the source

Keeping Secrets Updated

When you update secrets in your defaultBranch worktree:

# Sync all autoCopyFiles to an existing worktree
gw sync feat-existing-branch

# Or sync specific files
gw sync feat-existing-branch .env

4. Auto-Copy Strategies

Files That Should Be Copied

Environment variables:

".env",
".env.local",
".env.development"

Secrets and credentials:

"secrets/",
"keys/",
"ssl/certificates/"

Local configuration:

"config/local.json",
".vscode/settings.json",
"components/ui/.vercel/"

Cache directories (sometimes):

".next/cache/",
"public/uploads/"

Files That Should NOT Be Copied

Dependencies:

❌ node_modules/
❌ vendor/
❌ .pnpm-store/

Build artifacts:

❌ dist/
❌ build/
❌ .next/ (except cache)
❌ out/

Version control:

❌ .git (handled automatically)
❌ .gitignore (in source control)

IDE settings (usually):

❌ .idea/
❌ .vscode/ (unless team-shared)

Directory vs File Copying

Directory (recursive):

{
  "autoCopyFiles": ["secrets/"]
}

Copies:

secrets/
├── api-key.json      ← Copied
├── database.env      ← Copied
└── ssl/
    └── cert.pem      ← Copied (recursive)

Specific file:

{
  "autoCopyFiles": ["secrets/api-key.json"]
}

Copies only:

secrets/
└── api-key.json      ← Only this file

Glob Patterns (Not Currently Supported)

Currently, gw doesn't support glob patterns like:

• "*.env" - All .env files
• "config/**/*.json" - All JSON in config

Workaround: List files explicitly or copy parent directory.

5. Project-Type Configuration Patterns

Next.js Projects

Typical structure:

myapp/
├── .env
├── .env.local
├── .next/
├── public/
│   └── uploads/
├── components/
│   └── ui/
│       └── .vercel/
└── pages/

Recommended configuration:

{
  "root": "/projects/myapp.git",
  "defaultBranch": "main",
  "autoCopyFiles": [
    ".env",
    ".env.local",
    ".env.development",
    ".vercel/",
    "public/uploads/",
    "components/ui/.vercel/"
  ]
}

Why these files:

• .env* - Environment variables for different modes
• .vercel/ - Vercel deployment configuration
• public/uploads/ - User-uploaded assets
• components/ui/.vercel/ - Component-specific Vercel settings

See also: Next.js Setup Example

Node.js APIs

Typical structure:

api/
├── .env
├── src/
├── ssl/
│   ├── private.key
│   └── certificate.crt
└── config/
    └── local.json

Recommended configuration:

{
  "root": "/projects/api.git",
  "defaultBranch": "main",
  "autoCopyFiles": [
    ".env",
    "ssl/",
    "keys/",
    "secrets/",
    "config/local.json"
  ]
}

Why these files:

• .env - Database URLs, API keys, service credentials
• ssl/ - SSL certificates for HTTPS
• keys/ - JWT keys, encryption keys
• secrets/ - Service account credentials
• config/local.json - Local-only configuration overrides

React SPAs

Typical structure:

webapp/
├── .env
├── .env.local
├── public/
│   └── config.json
└── src/

Recommended configuration:

{
  "root": "/projects/webapp.git",
  "defaultBranch": "main",
  "autoCopyFiles": [
    ".env",
    ".env.local",
    "public/config.json"
  ]
}

Why these files:

• .env - Build-time environment variables
• .env.local - Local API endpoints, feature flags
• public/config.json - Runtime configuration

Monorepos (pnpm/Yarn/npm workspaces)

Typical structure:

monorepo/
├── .env                      # Root environment
├── packages/
│   ├── api/
│   │   └── .env             # Package-specific
│   ├── web/
│   │   └── .env
│   └── shared/
└── pnpm-workspace.yaml

Recommended configuration:

{
  "root": "/projects/monorepo.git",
  "defaultBranch": "main",
  "autoCopyFiles": [
    ".env",
    "packages/api/.env",
    "packages/web/.env",
    "packages/shared/config.local.json",
    ".vercel/"
  ]
}

Why these files:

• Root .env - Shared environment variables
• Package-specific .env - Service-specific configuration
• Shared config files - Cross-package configuration

See also: Monorepo Setup Example

Full-Stack Apps (Frontend + Backend)

Typical structure:

fullstack/
├── .env.backend
├── .env.frontend
├── backend/
│   ├── ssl/
│   └── secrets/
└── frontend/
    └── .vercel/

Recommended configuration:

{
  "root": "/projects/fullstack.git",
  "defaultBranch": "main",
  "autoCopyFiles": [
    ".env.backend",
    ".env.frontend",
    "backend/ssl/",
    "backend/secrets/",
    "frontend/.vercel/"
  ]
}

6. Team Configuration Management

Committing Configuration to Version Control

Recommended approach:

# Add .gw/config.json to git
git add .gw/config.json
git commit -m "chore: add gw configuration for team"
git push

Benefits:

• Team members get configuration automatically
• Consistent workflow across team
• Version-controlled changes to auto-copy patterns
• Easy onboarding for new developers

What to include:

• root - Can be a template, team members adjust locally
• defaultBranch - Should match team's workflow
• autoCopyFiles - Should include all shared secrets/configs

Team-Wide vs Personal File Patterns

Team-wide (commit to repo):

{
  "autoCopyFiles": [
    ".env.template",
    "ssl/development-cert.pem",
    "config/shared.json"
  ]
}

Personal (each developer customizes):

# Copy team config
cp .gw/config.json .gw/config.local.json

# Add personal files
vim .gw/config.local.json
# Add: "path/to/my-secrets.env"

# .gw/config.local.json is in .gitignore

Documenting Auto-Copy Patterns

In README.md:

## Development Setup

### 1. Install gw

npm install -g @gw-tools/gw-tool

### 2. Configuration

The repository includes gw configuration (`.gw/config.json`) that automatically copies:

- `.env` - Environment variables (copy from `.env.example`)
- `ssl/` - Development SSL certificates
- `secrets/` - Service credentials (get from team lead)

### 3. Create Feature Worktree

gw add feature-name -b feature-name main

Files will be automatically copied from the main worktree.

Generating Documentation from Config

Use gw show-init to automatically generate a setup command from your current configuration:

# Generate the init command from current config
gw show-init
# Output: gw init --auto-copy-files .env,secrets/ --post-add 'pnpm install'

# Add to documentation automatically
echo "## Setup\n\n\`\`\`bash\n$(gw show-init)\n\`\`\`" >> README.md

# Copy to clipboard for sharing (macOS)
gw show-init | pbcopy

# Copy to clipboard for sharing (Linux)
gw show-init | xclip -selection clipboard

Benefits:

• Always accurate - generated from actual config
• Easy to share with team members
• Simple to document in README files
• Shows exact command to replicate your setup

Example documentation update:

## Quick Setup

To configure gw for this project, run:

\`\`\`bash
gw init --auto-copy-files .env,secrets/ --post-add 'pnpm install' --clean-threshold 14
\`\`\`

This will:
- Auto-copy `.env` and `secrets/` directory when creating worktrees
- Run `pnpm install` after each worktree creation
- Clean up worktrees older than 14 days

Onboarding New Developers

Onboarding checklist:

1. Clone repository
2. Install gw: npm install -g @gw-tools/gw-tool
3. Set up secrets (one-time):

   cp .env.example .env
   # Get secrets from team lead or secret manager

1. Create first worktree:

   gw add feature-onboarding -b feature-onboarding main
   # Automatically copies configured files

7. Advanced Configuration Techniques

Multiple Source Worktrees

Scenario: Different features copy from different sources.

# Feature branches copy from develop
gw add feature-x -b feature-x

# Hotfixes copy from main
gw add hotfix-y --from main -b hotfix-y

Configuration supports one default:

{
  "defaultBranch": "develop"
}

Override at runtime:

gw sync --from staging target-worktree .env

Environment-Specific Configurations

Scenario: Different environments need different files.

Approach: Use custom config files.

# Development
cp .gw/config.development.json .gw/config.json

# Production
cp .gw/config.production.json .gw/config.json

Integration with Secret Management Tools

1Password:

# After creating worktree, inject secrets
gw add feature-x
op inject -i feature-x/.env.template -o feature-x/.env

AWS Secrets Manager:

gw add feature-x
aws secretsmanager get-secret-value --secret-id myapp/dev \
  --query SecretString --output text > feature-x/.env

HashiCorp Vault:

gw add feature-x
vault kv get -field=.env secret/myapp > feature-x/.env

8. Troubleshooting Configuration

Config Not Being Detected

Problem:

$ gw add feature-x
Error: Could not find .gw/config.json

Solution:

# Initialize configuration
gw init

# Or specify root manually
gw init --root $(gw root)

Files Not Being Auto-Copied

Problem:

$ gw add feature-x
✓ Worktree created
# But .env is missing!

Diagnostics:

# Check configuration
cat .gw/config.json

# Check if file exists in source
ls ../main/.env

Solutions:

Solution A: Add to auto-copy:

gw init --auto-copy-files .env,.env.local

Solution B: Manual sync:

# Sync all autoCopyFiles from config
gw sync feature-x

# Or sync specific files
gw sync feature-x .env

Wrong Files Being Copied

Problem: Copying too many or wrong files.

Solution: Review and update autoCopyFiles:

# Edit configuration
vim .gw/config.json

# Remove unwanted patterns
# Add specific files instead of directories

Path Resolution Issues

Problem:

$ gw add feature-x
Error: Source file not found: secrets/api-key.json

Solution:

Ensure paths are relative to repository root:

{
  "autoCopyFiles": [
    "secrets/api-key.json"  // ✓ Relative to root
  ]
}

Not:

{
  "autoCopyFiles": [
    "/Users/you/projects/myapp/secrets/api-key.json"  // ✗ Absolute path
  ]
}

Summary

You now understand:

• ✅ How gw configuration works (.gw/config.json)
• ✅ All configuration options (root, defaultBranch, autoCopyFiles)
• ✅ What files to auto-copy for different project types
• ✅ Team configuration management and onboarding
• ✅ Advanced techniques for complex workflows
• ✅ Troubleshooting common configuration issues

Next Steps

1. Configure gw for your project using a template
2. Read project-specific examples (Next.js, Monorepo)
3. Explore advanced parallel development

*Part of the gw-tools skills collection*