A powerful shell function that simplifies creating and managing Git worktrees for parallel development workflows. Perfect for developers who need to work on multiple features simultaneously or want to quickly spin up isolated environments for testing with AI coding assistants like Claude Code, Cursor, or Augment.

• Complete Worktree Management: Create, list, switch, and remove worktrees with simple commands
• Smart Branch Creation: Automatically creates a new branch and worktree in one command
• Flexible Starting Points: Base your new worktree on branches, tags, or specific commits
• Intelligent Updates: Automatically pulls latest changes when branching from a local branch, skips pulling for remote refs, commits, or tags
• Clean Organization: Creates worktrees in sibling directories with descriptive names
• Safe Operations: Preserves your original directory's state completely untouched
• Branch Name Sanitization: Automatically converts special characters to hyphens for filesystem compatibility
• Error Recovery: Automatic cleanup on failure with proper error handling
• Cross-Platform: Works on macOS, Linux, and other Unix-like systems
• Shell Completion: Bash completion support for improved productivity

• Git 2.5+ (for worktree support)
• Bash or Zsh shell

1. Clone this repository:

git clone https://github.com/levindixon/gwadd.git
cd gwadd

2. Run the installer:

./install.sh

3. Reload your shell:

source ~/.bashrc  # or ~/.zshrc

1. Clone this repository
2. Source the script in your shell configuration:

For Bash (~/.bashrc):

source /path/to/gwadd/gwadd.sh

For Zsh (~/.zshrc):

source /path/to/gwadd/gwadd.sh

gwadd [COMMAND] [OPTIONS]

Commands:

• 🟢 create - Create a new worktree (default if no command specified)
• 🟢 list - List all worktrees
• 🔴 switch - Switch to an existing worktree
• 🔴 remove - Remove a worktree

Running switch | remove will corrupt PATH in your current terminal session. 😅

Create a new worktree based on your local main/master branch:

gwadd feature-xyz
# or explicitly: gwadd create feature-xyz

Create from a specific local branch (pulls latest from origin):

gwadd feature-xyz develop

Create from a remote branch (uses exact state, no pulling):

gwadd feature-xyz origin/develop

Create from a specific commit:

gwadd bugfix-123 abc1234

Create from a tag:

gwadd release-prep v2.1.0

Create from a relative commit:

gwadd experiment HEAD~5

List all worktrees:

gwadd list

Switch to a worktree:

gwadd switch feature-xyz

Remove a worktree:

gwadd remove feature-xyz

Run multiple AI coding assistants simultaneously on different features:

# Terminal 1: Claude Code on feature A
gwadd feature-auth
claude-code .

# Terminal 2: Cursor on feature B
gwadd feature-payments
cursor .

# Terminal 3: Augment on bug fix
gwadd bugfix-memory-leak
augment .

Switch between multiple features without stashing or committing:

# Working on main feature
gwadd feature-redesign

# Urgent bug comes in
gwadd hotfix-prod-issue main

# Review a colleague's PR
gwadd review-pr-456 origin/colleague-branch

Test risky changes without affecting your main working directory:

gwadd experiment-refactor
# Make breaking changes, run tests, etc.
# Original directory remains untouched

1. Validates Arguments: Ensures you're in a Git repository and checks provided arguments
2. Determines Starting Point: Uses your local main/master by default, or your specified branch/commit/tag
3. Creates Worktree: Sets up a new worktree in a sibling directory named {repo}-{branch}
4. Smart Updates:
   • If starting from a local branch: Pulls latest changes from origin
   • If starting from a remote ref, commit, or tag: Skips pulling to preserve exact state
5. Switches Context: Automatically changes to the new worktree directory

Given a repository at /path/to/my-project, running:

gwadd feature-auth

Creates:

/path/to/
├── my-project/          (original, unchanged)
└── my-project-feature-auth/  (new worktree)

• Non-destructive: Never modifies your original working directory
• Collision Prevention: Checks if worktree directory already exists
• Validation: Verifies all Git references before creating worktrees
• Error Handling: Graceful failure with helpful error messages
• Automatic Cleanup: Uses error traps to clean up failed worktree creation attempts

1. Naming Convention: Use descriptive branch names that indicate the feature or fix
2. Quick Switching: Use gwadd switch <branch> to jump between worktrees
3. Cleanup: Use gwadd remove <branch> for safe worktree removal
4. List Worktrees: Use gwadd list to see all worktrees with current one highlighted
5. Detached HEAD: The list command properly handles and displays detached HEAD states
6. Tab Completion: If using bash, tab completion is available for commands and branch names

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

This project is licensed under the MIT License - see the LICENSE file for details.

• Original Concept & Design: Levin Dixon
• Implementation & Documentation: Written entirely by Claude (Anthropic's AI assistant)
• Purpose: Created to streamline parallel development workflows with modern AI coding assistants while maintaining clean Git practices

This entire project, including all code, documentation, and tests, was developed by Claude in collaboration with Levin Dixon.

"command not found" error

• Ensure you've sourced the script in your shell configuration
• Run source ~/.bashrc (or ~/.zshrc) or start a new terminal

"Not a git repository" error

• Make sure you're running gwadd from within a git repository

Branch name sanitization

• Special characters in branch names are automatically converted to hyphens
• Example: feature/new-ui becomes feature-new-ui in the directory name

Worktree already exists

• Use gwadd list to see existing worktrees
• Remove the existing worktree with gwadd remove <branch>

Note: This tool is a shell function, not a standalone executable. It must be sourced in your shell configuration to work properly.