Skip to main content
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

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

​
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 ManagerCommand
pnpmpnpm install
npmnpm install
yarnyarn install
bunbun 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

1
Step 1: Create First Worktree
2
On first use, GWTree creates the config with defaults:
3
gwt feature-name
4
Step 2: Adjust Settings
5
Open and modify the config:
6
gwt config
7
Edit the JSON:
8
{
  "editor": "cursor",
  "installDeps": true,
  "lastPm": "pnpm"
}
9
Step 3: Test Configuration
10
Create another worktree to test settings:
11
gwt test-config -y
12
Step 4: Fine-tune
13
Adjust based on your workflow:
14
  • Disable installDeps for faster creation
  • Change editor to match your preference
  • Set lastPm to your preferred package manager

    • ​
    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