Skip to main content
GWTree makes it easy to create new git worktrees with an interactive guided workflow. This guide covers creating a single worktree at a time.

​
Quick Start

Create a worktree with default settings: 
gwt feature-name
Or run interactively to enter the name: 
gwt

​
Interactive Workflow

When you run gwt without arguments, you’ll be guided through an interactive workflow:
1
Step 1: Handle Uncommitted Changes
2
If you have uncommitted changes, GWTree will prompt you:
3
◆  Uncommitted changes detected:
│  ○ Stash changes
│  ○ Ignore and continue
│  ○ Cancel
4
  • Stash changes: Runs git stash to save your changes
  • Ignore and continue: Proceeds without stashing
  • Cancel: Exits the workflow
    • 5
    Step 2: Switch to Base Branch
    6
    If you’re not on the main branch (main/master), you’ll be prompted:
    7
    ◆  Not on main (currently on feature-branch):
│  ○ Switch to main
│  ○ Ignore and continue
│  ○ Cancel
    8
    Selecting “Switch to main” runs git checkout main.
    9
    Step 3: Pull Latest Changes
    10
    If a remote is configured, you’ll be asked to pull:
    11
    ◆  Pull latest from origin/main?
│  ○ Yes, git pull --rebase
│  ○ Skip
    12
    Selecting “Yes” runs git pull --rebase origin main to sync with remote.
    13
    Step 4: Enter Worktree Name
    14
    You’ll see a preview of the directory structure:
    15
    /path/to/parent/myrepo-<name>

Press ESC to set worktree and branch names separately

◆  Worktree & branch name:
│  feature-name
    16
    By default, the name you enter will be used for both the worktree directory and git branch.
    17
    Directory naming pattern: {repo}-{name}
    18
    For example, if your repo is myrepo and you enter feature-auth, the worktree will be created at:
    19
    ../myrepo-feature-auth
    20
    Separate Worktree and Branch Names
    21
    Press ESC at the name prompt to enter worktree and branch names separately:
    22
    ◆  Worktree name:
│  feature-auth

◆  Branch name:
│  user/john/auth-feature
    23
    This is useful when you want different naming conventions for directories vs. branches.
    24
    Step 5: Automatic Setup
    25
    GWTree automatically performs these operations:
    26
    │
│  ◆  Prune  git worktree prune
│  └  removes stale refs
│
│  ◆  Create  git worktree add -b "feature-name" .../myrepo-feature-name "main"
│  └  /path/to/parent/myrepo-feature-name
│
│  ◆  Install  pnpm install
│  └  installs dependencies
│
│  ◆  Open  code .../myrepo-feature-name
│  └  opens in editor
│
└  Done  cd ../myrepo-feature-name
    27
    The workflow:
    28
  • Prunes stale worktree references
  • Creates the worktree with a new branch from main
  • Installs dependencies (if configured)
  • Opens in your editor (if configured)
  • Shows the cd command to navigate to the new worktree

    • ​
    Branch Name Conflicts

    If a branch with your chosen name already exists, GWTree automatically appends a counter: 
    feature-name    # Already exists
feature-name-1  # Created instead

    ​
    Skip Prompts Mode

    Use the -y or --yes flag to skip all interactive prompts and use defaults: 
    gwt feature-name -y
    With -y flag:
    • Uncommitted changes are automatically stashed
    • Automatically switches to main branch
    • Automatically pulls from remote
    • No editor/dependency prompts (uses saved config)

    ​
    Skip Editor

    Prevent opening the editor after creation: 
    gwt feature-name -x
# or
gwt feature-name --no-editor

    ​
    Examples

    ​
    Create with Interactive Prompts

    gwt
# Enter name when prompted

    ​
    Create with Name Argument

    gwt bug-fix
# Creates: ../myrepo-bug-fix
# Branch: bug-fix

    ​
    Quick Creation (Skip All Prompts)

    gwt feature/new-api -y
# Creates worktree immediately with defaults

    ​
    Create Without Opening Editor

    gwt refactor -x
# Creates but doesn't open in editor

    ​
    Valid Names

    Worktree and branch names must match the pattern: [a-zA-Z0-9._/-]+ Valid examples:
    • feature-name
    • user/john/feature
    • feat.new-api
    • 123-bug-fix
    Invalid examples:
    • feature name (spaces not allowed)
    • feature@name (@ not allowed)

    ​
    What Happens Under the Hood

    When you create a worktree, GWTree:
    1. Detects your git repository root
    2. Identifies the main branch (main or master)
    3. Creates the worktree directory at the same level as your repo
    4. Creates a new branch from main
    5. Records the worktree in ~/.gwtree/worktrees.json
    6. Detects package manager from lockfiles (pnpm-lock.yaml, package-lock.json, etc.)
    7. Installs dependencies if configured
    8. Opens in your configured editor

    ​
    Next Steps