A comprehensive zsh function suite for effortless git worktree management, enabling developers to work with multiple branches simultaneously in separate directories.
- Overview
- Features
- Installation
- Prerequisites
- Usage
- Examples
- Development
- Troubleshooting
- Performance
- Changelog
- License
Git Worktree Zsh provides intelligent automation for git worktree management, allowing developers to seamlessly switch between multiple branches without the overhead of traditional branch switching. Perfect for feature development, bug fixes, and code reviews requiring parallel work streams.
Target Audience:
- Developers working with multiple feature branches simultaneously
- Teams requiring parallel development workflows
- Code reviewers needing to test multiple pull requests
- Open source contributors managing complex branching strategies
- Clean Organization: Worktrees are created in dedicated "{project-name}-worktrees/" directories
- No Directory Clutter: Prevents scattering worktree directories across the parent directory
- Intuitive Layout: Easy to locate and manage multiple worktrees for the same project
- Automatic Container Creation: Worktree container directories are created automatically as needed
- Smart Strategy Selection: Automatically detects whether to create new branches or checkout existing ones
- Local & Remote Awareness: Seamlessly handles local branches, remote tracking branches, and new branch creation
- Conflict Prevention: Prevents worktree conflicts and provides clear guidance when issues arise
- Comprehensive Validation: Branch names, filesystem permissions, disk space, and git repository state
- Helpful Error Messages: Actionable suggestions for resolving common issues
- Automatic Cleanup: Failed operations are properly cleaned up to prevent corrupted state
- One-Command Workflow: Create and navigate to worktrees in a single command
- Organized Structure: Worktrees are created in dedicated "{project-name}-worktrees/" directories
- Zsh Completion: Intelligent tab completion for branch names from local and remote repositories
- Progress Indicators: Color-coded output with clear status messages
- Dry Run Mode: Preview operations before execution
- Cross-Platform: Native support for macOS, Linux, and Windows WSL
- Framework Integration: Compatible with Oh My Zsh, Prezto, and other zsh frameworks
- Minimal Dependencies: Only requires git 2.5+ and zsh 5.0+
- Fast Execution: Optimized for repositories with hundreds of branches
- Download the function file:
# Create config directory if it doesn't exist
mkdir -p ~/.config
# Download the git-worktree.zsh file directly from this repository
curl -fsSL https://raw.githubusercontent.com/retsohuang/git-worktree-zsh/master/git-worktree.zsh > ~/.config/git-worktree.zsh- Add to your zsh configuration:
echo "source ~/.config/git-worktree.zsh" >> ~/.zshrc- Reload your shell:
source ~/.zshrc- Verify installation:
gwt-create --help- Clone to custom plugins directory:
git clone https://github.com/retsohuang/git-worktree-zsh.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/git-worktree- Add to your Oh My Zsh plugins:
# In ~/.zshrc, add git-worktree to the plugins array
plugins=(git git-worktree other-plugins)- Restart your terminal or reload zsh:
exec zsh# Coming soon
brew install git-worktree-zsh# Add to ~/.zshrc
zinit load "retsohuang/git-worktree-zsh"Note for Package Managers: After adding the configuration to your ~/.zshrc file, restart your terminal or run source ~/.zshrc to reload the configuration. The package managers will automatically download and install the function for you.
Required:
- Git: Version 2.5 or higher (for
git worktreesupport) - Zsh: Version 5.0 or higher
- Unix-like System: macOS, Linux, or Windows WSL
Optional:
- Oh My Zsh: For enhanced plugin integration
- bats-core: For running development tests
Compatibility Matrix:
| Platform | Git Version | Zsh Version | Status |
|---|---|---|---|
| macOS 10.15+ | 2.5+ | 5.0+ | ✅ Primary |
| Ubuntu 20.04+ | 2.5+ | 5.0+ | ✅ Primary |
| Windows WSL2 | 2.5+ | 5.0+ | ✅ Secondary |
| CentOS 8+ | 2.5+ | 5.0+ | ✅ Secondary |
Create a new worktree for a new branch:
gwt-create feature/user-authenticationCreate a worktree with custom directory name:
gwt-create feature/complex-name simple-authPreview operations without making changes:
gwt-create --dry-run experimental-branchWork with existing branches:
# Checkout existing local branch in new worktree
gwt-create existing-local-branch
# Create local tracking branch from remote
gwt-create origin/remote-feature-branchComplex branching scenarios:
# Handle branches with special characters
gwt-create "feature/user-auth/oauth2.0"
# Create worktree in specific location
gwt-create hotfix/critical-bug ../hotfix-directoryCreate a git worktree with intelligent branch handling and automatic configuration file copying.
Syntax:
gwt-create <branch-name> [target-directory] [options]Parameters:
branch-name: Name of the branch to create or checkout (required)target-directory: Custom directory name (optional, defaults to sanitized branch name)
Options:
-h, --help: Display usage information--dry-run: Show what would be done without making changes
Automatically copy development files and directories to new worktrees by creating a .gwt-config file in your repository root. This file specifies which files and directories should be copied to maintain consistent development environments across worktrees.
Location Priority:
- Current directory (
./.gwt-config) - Repository root (
$(git rev-parse --show-toplevel)/.gwt-config)
File Format:
- One file/directory path per line
- Comments start with
# - Empty lines are ignored
- Supports glob patterns (
*.md,.vscode/*) - Supports exclusion patterns with
!prefix (!README.md) - Whitespace is automatically trimmed
Example .gwt-config file:
# Git Worktree Configuration
# Development files to copy to new worktrees
# Claude AI configuration
.claude
# Project documentation for Claude
CLAUDE.md
# Agent OS specifications and configuration
.agent-os/
# IDE settings
.vscode/
.idea/
# Configuration files
*.json
!package-lock.json
# Exclude temporary files
!.vscode/temp.logCommon Use Cases:
- AI Development: Copy
.claude,CLAUDE.md,.agent-os/for Claude AI workflows - IDE Settings: Copy
.vscode/,.idea/for consistent editor configuration - Project Configuration: Copy config files while excluding generated ones
- Documentation: Copy project-specific documentation files
Supported Patterns:
# Exact files
.claude
CLAUDE.md
# Directories (trailing slash recommended)
.vscode/
.agent-os/
# Glob patterns
*.md
.vscode/*
config/*.json
# Exclusions
!README.md
!.vscode/temp.log
!node_modules/Branch Strategy Detection:
The function automatically determines the appropriate strategy:
- Local Branch Exists: Creates worktree from existing local branch
- Remote Branch Exists: Creates local tracking branch and worktree
- New Branch: Creates new branch from current HEAD
Directory Structure:
Worktrees are organized in dedicated container directories:
parent-directory/
├── main-repo/ # Your original repository
└── main-repo-worktrees/ # Organized worktree container
├── feature-branch/ # Worktree for feature/branch
├── hotfix-123/ # Worktree for hotfix/123
└── user-dashboard/ # Worktree for feature/user-dashboard
# Start working on a new feature
cd ~/projects/my-app
gwt-create feature/user-dashboard
# This creates:
# - New branch 'feature/user-dashboard'
# - Worktree at ~/projects/my-app-worktrees/user-dashboard/
# - Automatically navigates to the new directory
# Continue development
git add .
git commit -m "Add user dashboard components"
# Switch to working on a bug fix (in parallel)
cd ~/projects/my-app # Back to main repo
gwt-create hotfix/login-issue
# Work on multiple features simultaneously
# Main repo: ~/projects/my-app/
# Feature work: ~/projects/my-app-worktrees/user-dashboard/
# Hotfix work: ~/projects/my-app-worktrees/login-issue/# Review a pull request locally (requires manual fetch first)
git fetch origin pull/123/head:pr/123-new-authentication
gwt-create pr/123-new-authentication
# Test an existing feature branch
gwt-create feature/oauth-integration
# Compare implementations side by side
# Each worktree is a separate directory with full git functionality# Create release preparation worktree
gwt-create release/v2.1.0
# Create hotfix worktree for current release
gwt-create hotfix/v2.0.1# Set up .gwt-config for consistent development environments
echo ".claude\nCLAUDE.md\n.vscode/" > .gwt-config
# Create worktree - config files are automatically copied
gwt-create feature/new-dashboard
# Your development setup is now ready in the new worktree:
# ~/projects/my-app-worktrees/new-dashboard/
# ├── .claude # Copied automatically
# ├── CLAUDE.md # Copied automatically
# ├── .vscode/ # Copied automatically
# └── [source code] # Git worktree content# If directory already exists
$ gwt-create feature/existing
Error: Directory '../my-project-worktrees/existing' already exists
Please choose a different directory name or remove the existing directory.
# Solution: Use custom directory name
$ gwt-create feature/existing feature-v2
# If branch is already checked out elsewhere
$ gwt-create main
Error: Failed to create worktree from local branch 'main'
Possible causes: Branch is checked out elsewhere, filesystem issues, or corrupted branch
Suggestion: Check 'git worktree list' to see where the branch might be in useWe welcome contributions! Please see our comprehensive Contributing Guide for detailed information on:
- Setting up your development environment
- Understanding our layered testing strategy
- Following coding standards and best practices
- Submitting pull requests
- Feature protection guidelines
Quick Start:
# Fork, clone, and set up
git clone https://github.com/YOUR_GITHUB_USERNAME/git-worktree-zsh.git
cd git-worktree-zsh
brew install bats-core # or apt-get install bats
# Test your changes
./scripts/test-layered.sh
# Submit your PR with tests and documentationCore Components:
gwt-create: Main function orchestrating worktree creation- Validation Layer: Input sanitization and environment checking
- Strategy Engine: Branch detection and worktree creation logic
- Error Handling: Comprehensive error recovery and cleanup
- Completion System: Zsh tab completion integration
Function Dependencies:
gwt-create
├── _gwt_show_usage
├── _gwt_validate_branch_name
├── _gwt_check_git_repo
├── _gwt_check_not_in_worktree
├── _gwt_determine_branch_strategy
├── _gwt_resolve_target_directory
├── _gwt_create_worktree
└── _gwt_cleanup_failed_worktree
Design Principles:
- Fail Fast: Early validation prevents partial state
- Clear Feedback: Every operation provides status updates
- Automatic Recovery: Failed operations are cleaned up automatically
- Extensibility: Modular design enables feature additions
Problem: Function called outside of a git repository.
Solution:
# Navigate to your git repository first
cd /path/to/your/git/repo
gwt-create feature/my-branchProblem: Attempting to create worktree from within an existing worktree.
Solution:
# Navigate to main repository
cd $(git rev-parse --show-toplevel)
gwt-create feature/my-branchProblem: Target directory conflicts with existing file/folder.
Solutions:
# Use custom directory name
gwt-create existing-branch-name custom-directory
# Or remove the conflicting directory
rm -rf ../my-project-worktrees/conflicting-directory-name
gwt-create existing-branch-nameProblem: Less than 100MB available for worktree creation.
Solution:
# Free up disk space or use different location
df -h # Check available space
gwt-create feature/branch /path/with/more/space/branch-dirProblem: Branch is already active in another worktree.
Solution:
# List current worktrees
git worktree list
# Remove unused worktree if safe to do so
git worktree remove /path/to/unused/worktree
# Or create worktree for a different branch
gwt-create different-branch-nameLarge Repository Optimization:
For repositories with many branches (>100), consider:
# Use specific branch names instead of relying on completion
gwt-create specific-branch-name
# Limit remote branch fetching
git config remote.origin.fetch "+refs/heads/main:refs/remotes/origin/main"Enable verbose output for troubleshooting:
# Add to ~/.zshrc for debugging
export GWT_DEBUG=1Operation Performance (tested on 2023 MacBook Pro M2):
| Repository Size | Branches | Creation Time | Navigation Time |
|---|---|---|---|
| Small (< 100MB) | < 50 | ~0.5s | ~0.1s |
| Medium (< 1GB) | < 200 | ~1.2s | ~0.2s |
| Large (< 5GB) | < 500 | ~3.0s | ~0.3s |
Memory Usage: < 10MB peak during operation
Disk Space: Worktrees share object storage, minimal overhead
- Use specific branch names instead of wildcards
- Clean up unused worktrees regularly with
git worktree prune - Limit remote tracking for very large repositories
- Use SSD storage for best performance
See CHANGELOG.md for detailed version history, feature additions, bug fixes, and upcoming releases.
Current Version: Unreleased (in development) - Full-featured git worktree management with organized structure and comprehensive layered testing.
This project is licensed under the MIT License - see the LICENSE file for details.
Created by: Retso Huang
Maintained by: Retso Huang
Repository: git-worktree-zsh
Issues: Report bugs and feature requests
⭐ Star this project if you find it useful!