repo wt add

​

Syntax

repo wt add <branch>

​

Arguments

• <branch> (required): The branch name for the worktree

​

Behavior

​

1. Check for Existing Worktree

• Displays a message that the worktree exists
• Runs post-add hooks (e.g., directory navigation)
• Returns successfully without modification

​

2. Fetch Latest Changes

• Fetches from origin to ensure branch information is up-to-date
• Uses the bare repository configuration at .bare/

​

3. Branch Resolution

• If origin/<branch> exists, creates worktree from remote branch
• Sets up tracking relationship: branch -> origin/branch
• Automatically pulls latest changes from remote

• If <branch> exists locally but not remotely, uses local branch
• No tracking relationship is set

• If branch doesn’t exist locally or remotely, creates a new branch
• Branches off from the default branch (main/master)
• Does not set up remote tracking initially

​

4. Worktree Location

• Worktree path: /Users/dev/my-repo/feature-x/

​

5. Post-Add Hooks

• Navigate to the worktree directory
• Run environment setup commands
• Display custom messages

​

Examples

​

Create Worktree from Remote Branch

# Create worktree for existing remote branch
repo wt add feature/new-dashboard

# Output:
# Fetching origin...
# Created worktree: /Users/dev/my-repo/feature/new-dashboard

​

Create Worktree for New Branch

# Create worktree with new branch
repo wt add fix/login-bug

# Output:
# Fetching origin...
# Created worktree: /Users/dev/my-repo/fix/login-bug

​

Create Worktree from Local Branch

# If you have a local-only branch
repo wt add experimental-feature

# Output:
# Fetching origin...
# Created worktree: /Users/dev/my-repo/experimental-feature

​

Error Cases

​

Missing Branch Name

repo wt add

# Output:
# Error: Branch name is required
# Usage: repo wt add <branch>

​

Repository Root Not Found

# Running outside a repository
repo wt add my-branch

# Output:
# Error: Not in a repo-managed repository

​

Git Worktree Creation Failed

# If git worktree command fails
repo wt add invalid-branch

# Output:
# Error: Failed to create worktree for branch invalid-branch

• The branch name contains invalid characters
• Disk space is insufficient
• File permissions prevent directory creation

​

Tips and Best Practices

​

Branch Naming

• Use clear, descriptive branch names: feature/, fix/, refactor/ prefixes
• Avoid special characters that may cause filesystem issues
• Branch names become directory names, so keep them filesystem-friendly

​

Workflow Integration

# Create and navigate in one flow
repo wt add feature/api-v2 && repo wt go feature/api-v2

​

Handling Existing Worktrees

• No error occurs
• Worktree is not recreated
• Post-add hooks still run (useful for navigation)

# Safe to run multiple times
repo wt add feature-x  # Creates worktree
repo wt add feature-x  # Displays "already exists", runs hooks

​

Remote Tracking

• Tracking is automatically configured
• git pull and git push work without additional setup
• You can immediately start working with remote changes

​

Starting from Default Branch

• Usually main or master
• Automatically detected by Repo Manager
• Ensures consistent starting point for new work

​

See Also

• repo wt list - View all worktrees
• repo wt go - Navigate to a worktree
• repo wt rm - Remove a worktree
• repo wt pr - Create worktree from pull request