python-wt 0.1.0

The ultimate git worktree manager with beautiful TUI and modern CLI

wt - Git Worktree Manager

The ultimate git worktree manager with a beautiful TUI and modern CLI

Features • Installation • Quick Start • CLI Reference • TUI • Configuration • Contributing

---

Overview

pywt is a modern, powerful, and user-friendly git worktree manager that simplifies working with multiple git worktrees. Whether you're juggling multiple features, reviewing PRs, or maintaining several branches simultaneously, pywt makes it effortless with both a beautiful terminal user interface (TUI) and a comprehensive command-line interface (CLI).

Why wt?

• Intuitive TUI: Navigate and manage worktrees with an interactive, keyboard-driven interface
• Powerful CLI: Complete control from the command line with rich output
• Fast & Reliable: Built with async operations and comprehensive error handling
• Type-Safe: Fully typed with Pydantic models and mypy strict mode
• Configurable: Flexible configuration system with sensible defaults
• Modern Python: Built with Python 3.12+ and modern best practices

---

Features

Core Functionality

• Create Worktrees: Easily create new worktrees from existing or new branches
• List & Filter: View all worktrees with rich formatting and filtering options
• Delete & Cleanup: Remove worktrees with automatic branch cleanup
• Switch & Navigate: Quickly switch between worktrees
• Lock & Unlock: Protect worktrees from accidental deletion
• Prune & Repair: Clean up stale worktrees and repair broken references

User Experience

• Interactive TUI: Beautiful Textual-based interface with keyboard shortcuts
• Rich CLI Output: Colorful tables, emoji, and formatted output via Rich
• Smart Defaults: Sensible configuration with zero setup required
• Batch Operations: Perform operations on multiple worktrees simultaneously
• Auto-Setup: Run custom commands after creating worktrees (e.g., npm install)
• Git Integration: Deep integration with git for maximum reliability

Developer Features

• Type Safety: Full type coverage with Pydantic and mypy
• Error Handling: Comprehensive exception system with clear error messages
• Testing: High test coverage with pytest and async support
• Documentation: Clear docstrings and usage examples
• Performance: Parallel operations and intelligent caching
• Cross-Platform: Works on Linux, macOS, and Windows

---

Installation

Using pip

pip install pywt

Using pipx (Recommended)

pipx installs the package in an isolated environment:

pipx install pywt

Using uv (Fastest)

uv is the fastest Python package installer:

uv tool install pywt

From Source

git clone https://github.com/ajcasagrande/pywt.git
cd pywt
pip install -e ".[dev]"

Verify Installation

wt --version
# Output: wt version 1.0.0

---

Quick Start

CLI Quick Start

List all worktrees

# Simple list
wt list

# With detailed information
wt list --verbose

# Filter by branch pattern
wt list --filter "feature/*"

Create a new worktree

# Create from existing branch
wt create feature/new-api

# Create with new branch from main
wt create feature/new-ui --new-branch --from main

# Create in specific directory
wt create hotfix/bug-123 --path ../worktrees/hotfix-123

Delete a worktree

# Delete with confirmation
wt delete feature/old-feature

# Force delete without confirmation
wt delete feature/old-feature --force

# Keep the branch when deleting
wt delete feature/old-feature --keep-branch

Switch to a worktree

# Switch and cd to worktree
wt switch feature/new-api

# Just print the path (for scripting)
wt switch feature/new-api --print-only

TUI Quick Start

Launch the interactive TUI:

wt tui

Or simply:

wt

TUI Keyboard Shortcuts

Key	Action
↑ / ↓	Navigate worktrees
Enter	Switch to selected worktree
n	Create new worktree
d	Delete selected worktree
l	Toggle lock on worktree
r	Refresh worktree list
f	Open filter dialog
/	Search worktrees
?	Show help dialog
q	Quit

The beautiful wt TUI in action

---

CLI Reference

Global Options

wt [OPTIONS] COMMAND [ARGS]...

Options:

• --version: Show version and exit
• --help: Show help message and exit
• --config PATH: Use custom config file
• --no-color: Disable colored output
• --verbose: Enable verbose output
• --quiet: Suppress non-error output

Commands

wt list - List worktrees

List all git worktrees in the repository.

wt list [OPTIONS]

Options:

• --filter PATTERN: Filter worktrees by branch name pattern
• --sort-by FIELD: Sort by field (path, branch, updated)
• --reverse: Reverse sort order
• --format FORMAT: Output format (table, json, csv)
• --verbose, -v: Show detailed information

Examples:

# List all worktrees
wt list

# Show only feature branches
wt list --filter "feature/*"

# Output as JSON
wt list --format json

# Sort by last updated
wt list --sort-by updated

wt create - Create worktree

Create a new git worktree.

wt create BRANCH [OPTIONS]

Arguments:

• BRANCH: Branch name for the worktree

Options:

• --path PATH: Custom path for the worktree
• --new-branch, -b: Create a new branch
• --from REF: Base branch or commit (default: configured base_branch)
• --track REMOTE: Track a remote branch
• --no-setup: Skip running setup command
• --force, -f: Force creation (overwrite existing)
• --detach: Create with detached HEAD

Examples:

# Create from existing branch
wt create feature/login

# Create new branch from main
wt create feature/new-feature -b --from main

# Create in specific location
wt create hotfix/bug --path ../worktrees/urgent-fix

# Create and track remote branch
wt create feature/api --track origin/feature/api

wt delete - Delete worktree

Delete an existing git worktree.

wt delete BRANCH [OPTIONS]

Arguments:

• BRANCH: Branch name or worktree path

Options:

• --force, -f: Force deletion without confirmation
• --keep-branch: Keep the branch after deleting worktree
• --cleanup: Also clean up remote-tracking branches

Examples:

# Delete with confirmation
wt delete feature/old-feature

# Force delete without prompt
wt delete feature/old-feature --force

# Delete but keep the branch
wt delete feature/old-feature --keep-branch

wt switch - Switch worktree

Switch to a different worktree (changes directory).

wt switch BRANCH [OPTIONS]

Arguments:

• BRANCH: Branch name or worktree path

Options:

• --create, -c: Create worktree if it doesn't exist
• --print-only, -p: Only print the path without switching

Examples:

# Switch to worktree
wt switch feature/api

# Print path for scripting (use with cd $(wt switch -p feature/api))
wt switch --print-only feature/api

# Switch and create if needed
wt switch feature/new-feature --create

wt lock - Lock worktree

Lock a worktree to prevent deletion.

wt lock BRANCH [OPTIONS]

Arguments:

• BRANCH: Branch name or worktree path

Options:

• --reason TEXT: Reason for locking

Examples:

# Lock a worktree
wt lock feature/important

# Lock with reason
wt lock main --reason "Production branch - do not delete"

wt unlock - Unlock worktree

Unlock a previously locked worktree.

wt unlock BRANCH

Arguments:

• BRANCH: Branch name or worktree path

Examples:

wt unlock feature/important

wt prune - Prune worktrees

Remove stale worktree references.

wt prune [OPTIONS]

Options:

• --dry-run, -n: Show what would be pruned without doing it
• --verbose, -v: Show detailed information

Examples:

# Preview what will be pruned
wt prune --dry-run

# Actually prune stale worktrees
wt prune

wt repair - Repair worktrees

Repair administrative files in worktrees.

wt repair [PATH]

Arguments:

• PATH: Path to worktree to repair (default: current directory)

Examples:

# Repair current worktree
wt repair

# Repair specific worktree
wt repair ../worktrees/feature-branch

wt info - Show information

Display detailed information about the current or specified worktree.

wt info [BRANCH] [OPTIONS]

Arguments:

• BRANCH: Branch name or worktree path (default: current)

Options:

• --format FORMAT: Output format (text, json, yaml)

Examples:

# Show info for current worktree
wt info

# Show info for specific worktree as JSON
wt info feature/api --format json

wt tui - Launch TUI

Launch the interactive terminal user interface.

wt tui [OPTIONS]

Options:

• --theme THEME: Color theme (dark, light, auto)

Examples:

# Launch TUI
wt tui

# Launch with light theme
wt tui --theme light

---

TUI

The TUI provides an intuitive, keyboard-driven interface for managing worktrees.

Features

• Real-time Updates: Automatically refreshes worktree status
• Keyboard Navigation: Full keyboard control with vim-style keys
• Visual Indicators: Color-coded status, emoji, and icons
• Search & Filter: Quickly find worktrees with fuzzy search
• Batch Operations: Select multiple worktrees for bulk actions
• Context Help: Built-in help system with keyboard shortcuts

Screenshots

Main View

The main TUI view showing all worktrees with status indicators

Create Dialog

Interactive dialog for creating new worktrees

Filter View

Filtering worktrees by branch pattern

---

Configuration

wt uses a hierarchical configuration system with support for global and repository-specific settings.

Configuration Files

Configuration is loaded from the following locations (in order of precedence):

1. $REPO_ROOT/.wt.toml - Repository-specific config
2. $XDG_CONFIG_HOME/wt/config.toml - User config (Linux/macOS)
3. ~/.config/wt/config.toml - User config (fallback)
4. %APPDATA%/wt/config.toml - User config (Windows)

Configuration Format

Configuration uses TOML format:

# .wt.toml or ~/.config/wt/config.toml

[global]
# Default base branch for new worktrees
base_branch = "main"

# Command to run after creating a worktree
setup_command = "npm install && npm run build"

# Default remote name
remote_name = "origin"

# Maximum concurrent operations
max_concurrent = 4

# Automatically fetch from remote before operations
auto_fetch = true

# Clean up branches when deleting worktrees
cleanup_on_delete = true

# Default directory for new worktrees (relative to repo root)
worktree_dir = "../worktrees"

[ui]
# Enable colored output in CLI
colors = true

# Show emoji in output
show_emoji = true

# Rich table style (rounded, simple, heavy, etc.)
table_style = "rounded"

# Use pager for long output
pager = true

# Use compact display mode
compact = false

[performance]
# Enable caching of git operations
cache_enabled = true

# Cache TTL in seconds (0 = no expiration)
cache_ttl = 300

# Enable parallel git operations
parallel_operations = true

[logging]
# Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
level = "INFO"

# Log file path (null = no file logging)
file = null

# Log format string
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

[git]
# Default prefix for new branches (e.g., 'feature/')
default_branch_prefix = ""

# Path to git commit message template
commit_template = null

# Sign commits with GPG
gpg_sign = false

# Default pull strategy (merge, rebase, ff-only)
pull_strategy = "merge"

Environment Variables

Configuration can also be set via environment variables:

# Override base branch
export WT_GLOBAL_BASE_BRANCH="develop"

# Disable colors
export WT_UI_COLORS="false"

# Set log level
export WT_LOGGING_LEVEL="DEBUG"

Environment variable format: WT_<SECTION>_<KEY> (all uppercase)

Example Configurations

Minimal Setup

[global]
base_branch = "main"

Frontend Developer

[global]
base_branch = "develop"
setup_command = "npm ci && npm run build"
worktree_dir = "../wt"

[ui]
show_emoji = true
table_style = "rounded"

Enterprise Setup

[global]
base_branch = "main"
remote_name = "origin"
auto_fetch = true
cleanup_on_delete = false
max_concurrent = 8

[git]
gpg_sign = true
pull_strategy = "rebase"

[logging]
level = "INFO"
file = "~/.local/share/wt/wt.log"

[performance]
cache_enabled = true
cache_ttl = 600
parallel_operations = true

---

Development

Setup Development Environment

1. Clone the repository

   git clone https://github.com/yourusername/wt.git
   cd wt
   

2. Create virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install development dependencies

   pip install -e ".[dev]"
   

4. Install pre-commit hooks

   pre-commit install
   

Development Workflow

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=wt --cov-report=html

# Run specific test file
pytest tests/test_repository.py

# Run with verbose output
pytest -v

# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration

Code Quality

# Format code with ruff
ruff format .

# Lint code
ruff check .

# Fix auto-fixable issues
ruff check --fix .

# Type check with mypy
mypy src/wt

# Run all checks
ruff check . && ruff format --check . && mypy src/wt

Building Documentation

# Build HTML documentation
cd docs
make html

# View documentation
open _build/html/index.html

Building Package

# Build source and wheel distributions
python -m build

# Install locally
pip install dist/wt-*.whl

Project Structure

wt/
├── src/
│   └── wt/
│       ├── __init__.py          # Package initialization
│       ├── cli/                 # CLI implementation
│       │   ├── __init__.py
│       │   ├── main.py          # Main CLI entry point
│       │   └── commands/        # CLI command modules
│       ├── tui/                 # TUI implementation
│       │   ├── __init__.py
│       │   ├── app.py           # Main TUI application
│       │   └── widgets/         # Custom TUI widgets
│       ├── core/                # Core functionality
│       │   ├── __init__.py
│       │   ├── models.py        # Pydantic models
│       │   ├── exceptions.py   # Exception classes
│       │   └── repository.py   # Git repository operations
│       └── config/              # Configuration management
│           ├── __init__.py
│           ├── settings.py      # Settings models
│           └── loader.py        # Config file loader
├── tests/                       # Test suite
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── fixtures/                # Test fixtures
├── docs/                        # Documentation
│   ├── images/                  # Screenshots and diagrams
│   └── examples/                # Example configurations
├── pyproject.toml               # Project metadata and config
├── README.md                    # This file
└── LICENSE                      # MIT License

Technologies Used

• CLI Framework: cyclopts - Modern CLI framework
• TUI Framework: Textual - TUI framework for Python
• Rich Output: Rich - Beautiful terminal formatting
• Data Validation: Pydantic - Data validation and settings
• Testing: pytest - Testing framework
• Linting: Ruff - Fast Python linter
• Type Checking: mypy - Static type checker

---

Contributing

Contributions are welcome! Please follow these guidelines:

How to Contribute

1. Fork the repository

   Click the "Fork" button on GitHub.

2. Clone your fork

   git clone https://github.com/yourusername/wt.git
   cd wt
   

3. Create a feature branch

   git checkout -b feature/amazing-feature
   

4. Make your changes

   • Write code following the project style
   • Add tests for new functionality
   • Update documentation as needed

5. Run tests and checks

   # Run tests
   pytest
   
   # Run linting
   ruff check .
   
   # Run type checking
   mypy src/wt
   
   # Run formatting
   ruff format .
   

6. Commit your changes

   git add .
   git commit -m "feat: add amazing feature"
   

   Follow Conventional Commits format:

   • feat: - New feature
   • fix: - Bug fix
   • docs: - Documentation changes
   • test: - Test changes
   • refactor: - Code refactoring
   • style: - Code style changes
   • chore: - Maintenance tasks

7. Push to your fork

   git push origin feature/amazing-feature
   

8. Open a Pull Request

   Go to the original repository and click "New Pull Request".

Code Style

• Follow PEP 8 style guide
• Use type hints for all functions and methods
• Write docstrings for all public APIs (Google style)
• Keep functions small and focused
• Maintain high test coverage (>90%)

Testing Guidelines

• Write unit tests for all new code
• Include integration tests for complex features
• Use meaningful test names that describe what is being tested
• Mock external dependencies in unit tests
• Ensure all tests pass before submitting PR

Documentation

• Update README.md for user-facing changes
• Add docstrings to all public functions and classes
• Include examples in docstrings
• Update CLI help text for command changes

Getting Help

• Open an issue for bug reports
• Use discussions for questions
• Check existing issues before creating new ones
• Provide minimal reproducible examples for bugs

---

Roadmap

Version 1.x

• Core worktree management (create, delete, list)
• Beautiful TUI with Textual
• Rich CLI output
• Configuration system
• Comprehensive test suite
• Shell completions (bash, zsh, fish)
• Git hooks integration
• Worktree templates

Version 2.x

• Remote worktree support
• Worktree groups and tagging
• Advanced filtering and search
• Worktree snapshots and backup
• Integration with popular tools (VS Code, JetBrains)
• Performance optimizations
• Plugin system

---

FAQ

Why use worktrees instead of branches?

Git worktrees allow you to have multiple branches checked out simultaneously in different directories. This is useful for:

• Working on multiple features in parallel
• Reviewing PRs without stashing changes
• Running different versions side-by-side
• Comparing code across branches

Can I use wt with existing worktrees?

Yes! wt detects and manages all worktrees in your repository, whether created with wt or git worktree.

Does wt modify my git configuration?

No, wt uses standard git commands and doesn't modify your git configuration. All worktrees are created using git worktree under the hood.

What's the difference between CLI and TUI?

• CLI: Command-line interface for scripting and automation
• TUI: Interactive terminal UI for visual management

Both provide the same functionality, choose based on your preference.

How do I uninstall wt?

pip uninstall wt
# or
pipx uninstall wt
# or
uv tool uninstall wt

Where are configuration files stored?

• Linux/macOS: ~/.config/wt/config.toml
• Windows: %APPDATA%/wt/config.toml
• Repository-specific: $REPO_ROOT/.wt.toml

---

License

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

MIT License

Copyright (c) 2024 Anthony

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Acknowledgments

• Built with Textual by Textualize
• CLI powered by cyclopts
• Beautiful output via Rich
• Inspired by the git worktree workflow

---

Support

If you find wt useful, please:

• Star the repository on GitHub
• Share it with other developers
• Report bugs and request features
• Contribute code or documentation

---

Links

• Homepage: https://github.com/yourusername/wt
• Documentation: https://wt.readthedocs.io
• PyPI: https://pypi.org/project/wt/
• Issues: https://github.com/yourusername/wt/issues
• Discussions: https://github.com/yourusername/wt/discussions

---

Made with ❤️ by developers, for developers