Creating Worktrees

Learn how to create single git worktrees with interactive prompts

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:

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

• Learn about batch creation to create multiple worktrees at once
• Configure automatic behaviors like editor and dependency installation
• Explore managing worktrees with list, status, and remove commands