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"
  ]
}

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

---

3. 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.

---

4. 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/"
  ]
}

---

5. 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.

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
   

4. Create first worktree:

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

---

6. 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

---

7. 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