Naming Patterns

The `{repo}-{name}` Pattern

GWTree follows a consistent naming pattern for all worktrees:

{repository-name}-{worktree-name}

This pattern ensures:

Predictability: Always know where to find worktrees
Organization: Related worktrees are grouped alphabetically
Clarity: The repository origin is immediately visible
Uniqueness: Avoid conflicts with existing directories

Pattern Implementation

From the source code (src/commands/create.ts:47, 224):

const repoName = basename(gitRoot);
// ...
const worktreeName = `${repoName}-${worktreeSuffix}`;
const worktreePath = join(parentDir, worktreeName);

GWTree automatically:

Detects the repository name from the git root directory
Combines it with your chosen worktree name
Creates the directory in the parent folder

Directory Structure

Single Repository Example

~/projects/
├── my-app/                 # Original repository
├── my-app-feature-auth/    # Authentication feature
├── my-app-bugfix-login/    # Login bug fix
└── my-app-refactor-api/    # API refactoring

Multi-Repository Example

~/projects/
├── frontend/
├── frontend-dashboard/
├── frontend-mobile/
├── backend/
├── backend-api/
└── backend-workers/

Worktrees for different repos naturally group together.

Naming Examples

Quick Creation

When you provide a name directly, it’s used for both the worktree and branch:

gwt feature-auth

Creates:

Directory: my-repo-feature-auth/
Branch: feature-auth

Interactive Creation

During interactive mode:

gwt
# Prompt shows: ~/projects/my-repo-<name>
# You enter: dashboard-redesign

Creates:

Directory: my-repo-dashboard-redesign/
Branch: dashboard-redesign

Separate Names (Advanced)

Press ESC during name input to specify different worktree and branch names:

gwt
# Press ESC
# Worktree name: ui-v2
# Branch name: feature/dashboard-redesign

Creates:

Directory: my-repo-ui-v2/
Branch: feature/dashboard-redesign

From src/commands/create.ts:181-221:

if (p.isCancel(nameInput)) {
  // ESC pressed - ask for worktree and branch names separately
  const worktreeInput = await p.text({
    message: 'Worktree name:',
    placeholder: 'feature-name',
  });
  // ...
  worktreeSuffix = worktreeInput as string;
  
  const branchInput = await p.text({
    message: 'Branch name:',
    placeholder: worktreeSuffix,
    defaultValue: worktreeSuffix,
  });
  // ...
  branchName = branchInput as string;
}

Valid Name Characters

GWTree validates names to ensure compatibility with both filesystems and git:

// From src/commands/create.ts:176-178
validate: (value) => {
  if (!value) return 'Name is required';
  if (!/^[a-zA-Z0-9._/-]+$/.test(value)) return 'Invalid name';
}

Allowed Characters

Valid

string

Letters: a-z, A-Z
Numbers: 0-9
Special: . (dot), _ (underscore), / (slash), - (hyphen)

Invalid characters:

Spaces: (use - or _ instead)
Special symbols: @, #, $, %, &, *, etc.

Naming Conventions

Feature Development

gwt feature-user-auth      # my-repo-feature-user-auth/
gwt feature-payment        # my-repo-feature-payment/
gwt feat/dark-mode         # my-repo-feat/dark-mode/

Bug Fixes

gwt bugfix-login           # my-repo-bugfix-login/
gwt fix/cors-issue         # my-repo-fix/cors-issue/
gwt hotfix-security        # my-repo-hotfix-security/

Experiments

gwt exp-new-framework      # my-repo-exp-new-framework/
gwt poc-ai-integration     # my-repo-poc-ai-integration/
gwt test-performance       # my-repo-test-performance/

Agent-Based Work

gwt auth api dashboard     # Multi-agent parallel work
# Creates:
# - my-repo-auth/
# - my-repo-api/
# - my-repo-dashboard/

Branch Name Conflicts

GWTree automatically handles branch name conflicts by appending a counter:

// From src/commands/create.ts:234-237
let newBranchForWorktree = branchName;
let counter = 1;
while (branches.includes(newBranchForWorktree)) {
  newBranchForWorktree = `${branchName}-${counter}`;
  counter++;
}

Example

If branch feature already exists:

gwt feature
# Creates: my-repo-feature/ with branch feature-1

gwt feature
# Creates: my-repo-feature-2/ with branch feature-2

For batch creation:

gwt test test test
# Creates:
# - my-repo-test/ (branch: test)
# - my-repo-test-2/ (branch: test-1)  
# - my-repo-test-3/ (branch: test-2)

From src/commands/create.ts:376-381:

let branchName = name;
let counter = 1;
while (branches.includes(branchName)) {
  branchName = `${name}-${counter}`;
  counter++;
}
branches.push(branchName); // Track for next iteration

Directory Path Preview

GWTree shows the full path before creation:

gwt
# Shows: /Users/dev/projects/my-repo-<name>

From src/commands/create.ts:169:

p.log.info(`${chalk.dim(parentDir + '/')}${repoName}-${chalk.green('<name>')}`);

This helps you:

Verify the parent directory location
Understand the naming pattern
Catch potential path issues early

Batch Creation Naming

Create multiple worktrees with custom names:

gwt auth api dashboard admin

Creates:

my-repo-auth/
my-repo-api/
my-repo-dashboard/
my-repo-admin/

Each worktree:

Has its own branch with the same name
Lives in the parent directory
Follows the {repo}-{name} pattern
Gets dependencies installed automatically (if configured)

Edge Cases

Directory Already Exists

If the worktree directory already exists:

// From src/commands/create.ts:227-230
if (existsSync(worktreePath)) {
  p.cancel(`Directory already exists: ${worktreePath}`);
  process.exit(1);
}

Solution: Choose a different name or remove the existing directory.

Long Repository Names

For repos with long names like my-super-long-repository-name:

# Creates: my-super-long-repository-name-feature-auth/
gwt feature-auth

Tip: Keep worktree names short to compensate for long repo names.

Special Characters in Repo Name

Repository names with special characters are preserved:

# Repo: my-app.io
# Creates: my-app.io-feature-auth/
gwt feature-auth

Finding Worktrees

List Command

View all worktrees for the current repository:

gwt ls

Output:

◆  feature-auth
└  /Users/dev/projects/my-repo-feature-auth

◆  api-refactor
└  /Users/dev/projects/my-repo-api-refactor

Remove by Name

The remove command searches by worktree name:

gwt rm
# Search: auth
# Shows: feature-auth my-repo-feature-auth

From src/commands/list.ts:168-172:

const choices = worktrees.map(wt => ({
  value: wt.path,
  name: `${wt.branch} ${chalk.dim(basename(wt.path))}`,
  description: wt.path
}));

Merge by Name

Merge using any of these identifiers:

# By branch name
gwt merge feature-auth

# By worktree name
gwt merge my-repo-feature-auth

# By suffix only
gwt merge auth

From src/commands/list.ts:467-471:

const wt = worktrees.find(w =>
  w.branch === name ||
  basename(w.path) === name ||
  basename(w.path) === `${repoName}-${name}`
);

Best Practices

Recommended naming:

Use descriptive, lowercase names: user-dashboard, payment-flow
Include context: fix-login-bug, refactor-api-layer
Keep it short: auth instead of authentication-and-authorization
Use hyphens for readability: api-v2 not apiv2

Avoid:

Generic names: test, temp, new
Version numbers alone: v1, v2
Ambiguous abbreviations: stuff, things, misc
Special characters: feat@1, fix#123

Pattern Benefits

Consistency Across Projects

The same pattern works for any repository:

# Frontend project
cd ~/projects/frontend
gwt dashboard
# Creates: frontend-dashboard/

# Backend project
cd ~/projects/backend-api
gwt webhooks
# Creates: backend-api-webhooks/

Tab completion works naturally:

cd ~/projects/my-<TAB>
# Autocompletes all: my-repo, my-repo-auth, my-repo-api

Clean Organization

Alphabetical sorting groups related worktrees:

ls ~/projects/
# backend/
# backend-api/
# backend-workers/
# frontend/
# frontend-admin/
# frontend-mobile/

Get Started

Core Concepts

Guides

Use Cases

Documentation Index

​The {repo}-{name} Pattern

​Pattern Implementation

​Directory Structure

​Single Repository Example

​Multi-Repository Example

​Naming Examples

​Quick Creation

​Interactive Creation

​Separate Names (Advanced)

​Valid Name Characters

​Allowed Characters

​Naming Conventions

​Feature Development

​Bug Fixes

​Experiments

​Agent-Based Work

​Branch Name Conflicts

​Example

​Directory Path Preview

​Batch Creation Naming

​Edge Cases

​Directory Already Exists

​Long Repository Names

​Special Characters in Repo Name

​Finding Worktrees

​List Command

​Remove by Name

​Merge by Name

​Best Practices

​Pattern Benefits

​Consistency Across Projects

​Easy Navigation

​Clean Organization

​Learn More

Git Worktrees

Multi-Agent Workflow

Build docs developers (and LLMs) love

The `{repo}-{name}` Pattern

Pattern Implementation

Directory Structure

Single Repository Example

Multi-Repository Example

Naming Examples

Quick Creation

Interactive Creation

Separate Names (Advanced)

Valid Name Characters

Allowed Characters

Naming Conventions

Feature Development

Bug Fixes

Experiments

Agent-Based Work

Branch Name Conflicts

Example

Directory Path Preview

Batch Creation Naming

Edge Cases

Directory Already Exists

Long Repository Names

Special Characters in Repo Name

Finding Worktrees

List Command

Remove by Name

Merge by Name

Best Practices

Pattern Benefits

Consistency Across Projects

Easy Navigation

Clean Organization

Learn More