Configuration

Configure GWTree behavior with editor, dependency installation, and package manager settings

GWTree stores configuration in a JSON file that controls automatic behaviors when creating worktrees.

Configuration File

GWTree uses a global configuration file stored at:

~/.config/configstore/gwtree.json

Open Configuration

Open the config file in your editor:

gwt config

This opens the file in your configured editor.

View Configuration Path

If you have editor set to none:

gwt config
# Outputs: /Users/username/.config/configstore/gwtree.json

Reset Configuration

Reset all settings to defaults:

gwt config reset

Output:

Config reset to defaults

Configuration Schema

The config file contains three main settings:

{
  "editor": "code",
  "installDeps": true,
  "lastPm": "pnpm"
}

editor

Controls which editor opens after creating a worktree.

Type: string
Options: "code", "cursor", "default", "none"
Default: "code"

Options

code

Opens worktrees in Visual Studio Code.

{
  "editor": "code"
}

Runs:

code "/path/to/worktree"

Requirements:

• VS Code installed
• code command in PATH

Behavior:

• Opens each worktree in a new window
• Batch creation opens multiple windows

cursor

Opens worktrees in Cursor editor.

{
  "editor": "cursor"
}

Runs:

cursor "/path/to/worktree"

Requirements:

• Cursor installed
• cursor command in PATH

Behavior:

• Opens each worktree in a new window
• Batch creation opens multiple windows

default

Uses the system default editor from $EDITOR environment variable.

{
  "editor": "default"
}

Runs:

$EDITOR "/path/to/worktree"

Falls back to vim if $EDITOR is not set.

Use cases:

• Remote development via SSH
• Terminal-based editors (vim, emacs, nano)
• Custom editor setups

none

Disables automatic editor opening.

{
  "editor": "none"
}

Use cases:

• Manual editor control
• Scripting and automation
• Batch creation without opening editors
• Resource-constrained environments

Skip Editor with Flag

Temporarily skip editor opening without changing config:

gwt feature-name -x
# or
gwt feature-name --no-editor

installDeps

Controls whether dependencies are automatically installed after creating a worktree.

Type: boolean
Default: true

Enable Dependency Installation

{
  "installDeps": true
}

When enabled:

• Detects package manager from lockfiles
• Runs install command automatically
• Uses lastPm as fallback if no lockfile found

Disable Dependency Installation

{
  "installDeps": false
}

When disabled:

• Skips installation step entirely
• Faster worktree creation
• Manual installation required

Package Manager Detection

GWTree detects the package manager in this order:

1. pnpm: If pnpm-lock.yaml exists
2. bun: If bun.lockb exists
3. yarn: If yarn.lock exists
4. npm: If package-lock.json exists
5. pnpm (default): If only package.json exists
6. lastPm: If no lockfiles found

Install Commands

Package Manager	Command
pnpm	pnpm install
npm	npm install
yarn	yarn install
bun	bun install

lastPm

Tracks the last package manager used successfully.

Type: string | null
Options: "pnpm", "npm", "yarn", "bun", null
Default: null

Automatic Updates

This field is automatically updated by GWTree:

{
  "lastPm": "pnpm"
}

When a worktree is created:

1. GWTree detects the package manager
2. Runs the install command
3. Updates lastPm to the detected package manager

Fallback Behavior

When no lockfile is found:

• If lastPm is set: Uses that package manager
• If lastPm is null: No installation occurs

This allows GWTree to remember your preference across worktrees.

Manual Configuration

You can manually set a preferred package manager:

{
  "lastPm": "bun"
}

This ensures bun is used when no lockfile is detected.

Configuration Examples

VS Code + Always Install

{
  "editor": "code",
  "installDeps": true,
  "lastPm": "pnpm"
}

Behavior:

• Opens worktrees in VS Code
• Installs dependencies automatically
• Prefers pnpm when no lockfile

Cursor + Skip Install

{
  "editor": "cursor",
  "installDeps": false,
  "lastPm": null
}

Behavior:

• Opens worktrees in Cursor
• Skips dependency installation
• No package manager fallback

Terminal Vim + NPM

{
  "editor": "default",
  "installDeps": true,
  "lastPm": "npm"
}

Behavior:

• Opens worktrees in $EDITOR (vim)
• Installs dependencies with npm
• Uses npm when no lockfile

No Editor + Manual Install

{
  "editor": "none",
  "installDeps": false,
  "lastPm": null
}

Behavior:

• No automatic editor opening
• No automatic dependency installation
• Maximum control, minimum automation

Fast Mode (CI/Scripting)

{
  "editor": "none",
  "installDeps": false,
  "lastPm": "pnpm"
}

Behavior:

• No editor opening
• No dependency installation
• Fast worktree creation for scripts

Configuration Workflow

Initial Setup

Common Adjustments

Switch to Cursor

gwt config
# Change: "editor": "code" → "editor": "cursor"

Disable Auto-install for Speed

gwt config
# Change: "installDeps": true → "installDeps": false

Prefer Bun

gwt config
# Change: "lastPm": "pnpm" → "lastPm": "bun"

Advanced Configuration

Per-Command Overrides

Config settings can be overridden per command:

# Skip editor even if config has editor set
gwt feature-name -x

# Use defaults even if installDeps is false
gwt feature-name -y

Team Configuration

For teams, you can share config via documentation:

// Recommended team config
{
  "editor": "code",
  "installDeps": true,
  "lastPm": "pnpm"
}

Each developer runs:

gwt config
# Paste team config

Environment-Specific Config

Development Machine

{
  "editor": "code",
  "installDeps": true,
  "lastPm": "pnpm"
}

Remote SSH Session

{
  "editor": "default",  // Uses vim
  "installDeps": false, // Slow over SSH
  "lastPm": null
}

CI/CD Pipeline

{
  "editor": "none",
  "installDeps": false,
  "lastPm": "npm"
}

Troubleshooting

Editor Not Opening

Problem: Editor configured but doesn’t open

Solutions:

1. Verify editor is installed
2. Check editor command is in PATH:
   which code
   which cursor
   
3. Try running command manually:
   code /path/to/test
   
4. Check config file:
   gwt config
   

Dependencies Not Installing

Problem: installDeps is true but nothing installs

Solutions:

1. Check installDeps setting:
   gwt config
   
2. Verify lockfile exists in repo
3. Set lastPm to preferred package manager
4. Check package manager is installed:
   which pnpm
   which npm
   

Wrong Package Manager

Problem: Using npm but want pnpm

Solutions:

1. Delete lockfiles from other package managers
2. Set lastPm to preferred:
   { "lastPm": "pnpm" }
   
3. Ensure lockfile exists:
   # Create pnpm lockfile
   pnpm install
   

Config Changes Not Applied

Problem: Edited config but behavior unchanged

Solutions:

1. Verify JSON syntax is valid
2. Check no trailing commas
3. Restart terminal/shell
4. View config path:
   gwt config  # Should show path
   
5. Reset and reconfigure:
   gwt config reset
   gwt config
   

Next Steps

• Apply your config by creating worktrees
• Learn about batch creation which respects config settings
• Explore managing worktrees to track your work