nwt (New Worktree) 🚀

A smart Git worktree manager specifically designed for Warp Terminal that creates isolated development environments with intelligent tab management.

✨ Features

• 🎯 Smart Branch Detection - Auto-detects your default branch (main, master, develop)
• 📁 Intelligent Worktree Management - Handles existing worktrees and branches gracefully
• 🔄 Smart Tab Reuse - Leverages Warp's tab management to reuse existing tabs when possible
• 🌿 Branch Name Support - Full support for complex branch names (feature/api/user-management)
• 💬 Clear Feedback - Descriptive status messages and error handling
• ⚡ Lightning Fast - Minimal overhead, maximum productivity

🎯 What Problem Does This Solve?

Traditional git workflow often involves:

• Stashing or committing incomplete work to switch branches
• Losing context when switching between features
• Manual terminal navigation between project directories
• Managing multiple terminal windows/tabs manually

nwt solves this by creating isolated worktrees for each branch and intelligently managing your Warp terminal tabs.

📦 Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/zdql/nwt/main/install.sh | bash

Manual Installation

1. Clone this repository:

   git clone https://github.com/zdql/nwt.git
   cd nwt

2. Run the installer:

   chmod +x install.sh
   ./install.sh

3. Reload your shell:

   source ~/.zshrc  # or ~/.bashrc

Manual Setup

If you prefer manual setup, add the contents of nwt.zsh to your shell configuration file (~/.zshrc or ~/.bashrc).

🚀 Usage

Basic Usage

# Create a new worktree and branch (auto-detects base branch)
nwt feature/user-authentication

# Create from a specific base branch
nwt feature/payment-integration develop

# Create a hotfix
nwt hotfix/critical-security-fix main

Advanced Examples

# Complex branch names with slashes
nwt feature/api/v2/user-management
nwt bugfix/ui/modal/close-button
nwt chore/deps/update-react-18

# Different base branches
nwt feature/new-ui main
nwt hotfix/prod-issue production
nwt experiment/new-arch develop

🧠 How It Works

Directory Structure

When you run nwt feature/user-auth from /path/to/myproject, it creates:

/path/to/
├── myproject/                    # Original repository
└── myproject-feature/user-auth/  # New worktree

Smart Behavior Matrix

Scenario	Behavior
New branch	Creates worktree + branch, opens in new Warp tab
Existing branch, no worktree	Creates worktree, opens in new Warp tab
Existing worktree	Opens existing worktree (reuses tab if available)
Already in target worktree	No-op (you're already there!)

Branch Detection Logic

1. Remote HEAD: Checks git symbolic-ref refs/remotes/origin/HEAD
2. Common branches: Looks for main → master → develop
3. Current branch: Falls back to your current branch (with warning)

🔧 Configuration

Environment Variables

# Force current tab behavior (optional)
export NWT_CURRENT_TAB=1  # Navigate in current tab instead of new window

Warp Integration

The script detects Warp terminal using the $WARP_IS_LOCAL_SHELL_SESSION environment variable and optimizes behavior accordingly.

📖 Command Reference

nwt <branch-name> [base-branch]

Parameters:

• branch-name: Name of the branch to create/navigate to (required)
• base-branch: Base branch for new branches (optional, auto-detected if not provided)

Aliases:

• nwt - Short form
• new_worktree - Full function name

Exit Codes:

• 0 - Success
• 1 - Error (not in git repo, worktree creation failed, etc.)

🛠️ Troubleshooting

Common Issues

"Error: Not in a git repository"

• Make sure you're running the command from within a git repository
• Check that git rev-parse --show-toplevel works

"Failed to create worktree"

• Ensure the target directory doesn't already exist
• Check git worktree permissions
• Verify the base branch exists

Warp doesn't open

• Ensure Warp is installed and in your Applications folder
• Check that the open command works: open -a "Warp" .

Debug Mode

Run with verbose output:

set -x  # Enable debug mode
nwt your-branch-name
set +x  # Disable debug mode

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Development Setup

git clone https://github.com/zdql/nwt.git
cd nwt
# Make your changes
# Test thoroughly

Testing

Test the function in different scenarios:

• New repository
• Repository with main/master branches
• Existing worktrees
• Complex branch names

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Warp Terminal for building an amazing terminal
• Git worktree feature for making isolated development environments possible
• The open source community for inspiration and best practices

🔗 Related Projects

• git-worktree-switcher
• git-extras
• forgit