Naming Patterns

Understanding the - naming convention and how GWTree structures worktrees

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:

1. Detects the repository name from the git root directory
2. Combines it with your chosen worktree name
3. 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/

Easy Navigation

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/

Learn More

Git Worktrees

Learn about git worktrees fundamentals

Multi-Agent Workflow

See how naming patterns enable parallel development