worktreeflow

Git workflow manager for feature branches using worktrees.

Quick Start

Using Dev Container (Recommended)

The fastest way to get started is using the dev container, which provides a pre-configured environment with Python, uv, and git.

Option 1: VS Code Dev Containers

1. Prerequisites:

   • Install Docker Desktop
   • Install VS Code
   • Install the Dev Containers extension

2. Open in Container:

   # Clone the repository
   git clone https://github.com/smorinlabs/worktreeflow.git
   cd worktreeflow
   
   # Open in VS Code
   code .

3. Reopen in Container:

   • VS Code will detect the .devcontainer configuration
   • Click "Reopen in Container" when prompted (or use Command Palette: Dev Containers: Reopen in Container)
   • Wait ~30 seconds for the container to build and start

4. Start Using:

   ./wtf --help
   ./wtf doctor

Option 2: GitHub Codespaces

1. Go to the repository on GitHub
2. Click the Code button → Codespaces tab → Create codespace on main
3. Your browser opens with a fully configured VS Code environment
4. Run ./wtf --help to get started

Benefits: Zero local setup, works from any device with a browser.

Local Installation (Without Dev Container)

If you prefer to run locally without Docker:

1. Prerequisites:

   • Python 3.9+
   • uv package manager

2. Install uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh

3. Run the tool:

   ./wtf --help

   The script automatically installs its dependencies via uv on first run.

Usage

# Check your environment
./wtf doctor

# Sync your fork's main branch
./wtf sync-main

# Create a new feature worktree
./wtf wt-new my-feature

# Publish your branch
./wtf wt-publish my-feature

# Create a pull request
./wtf wt-pr my-feature

# Update worktree with upstream changes
./wtf wt-update my-feature

# Clean up worktree after merge
./wtf wt-clean my-feature --confirm

For detailed documentation, run:

./wtf --help
./wtf tutorial
./wtf quickstart

Installation from PyPI

Once published, you can install worktreeflow via pip or pipx:

# Using pipx (recommended for CLI tools)
pipx install worktreeflow

# Or using pip
pip install worktreeflow

# Or using uv
uv tool install worktreeflow

Then use either the wtf or worktreeflow command:

# Short form
wtf --help
wtf doctor

# Full name (same functionality)
worktreeflow --help
worktreeflow doctor

Development

Setting Up Development Environment

The dev container includes:

• Python 3.12
• uv package manager
• git (latest)
• VS Code extensions: Ruff, Python, Pylance
• Auto-formatting on save

All dependencies are automatically installed via the wtf script's inline metadata.

Git Hooks with Lefthook

This project uses Lefthook for pre-commit hooks (ruff check, ruff format, ty).

# Install lefthook (https://github.com/evilmartians/lefthook/blob/master/docs/install.md)
# macOS
brew install lefthook

# npm
npm install -g @evilmartians/lefthook

# Then activate hooks in your local clone
lefthook install

Common Dev Tasks (Makefile)

make help        # Show all available targets
make test        # Run tests
make lint        # Run linting checks
make format      # Auto-format code
make typecheck   # Run ty type checking
make coverage    # Run tests with coverage (35% threshold)
make build       # Build the package
make clean       # Remove build artifacts
make version     # Show current version
make bump-patch  # Bump patch version (0.3.0 → 0.3.1)
make bump-minor  # Bump minor version (0.3.0 → 0.4.0)
make bump-major  # Bump major version (0.3.0 → 1.0.0)
make release     # Sync, commit, tag (run make bump-* first)

Shell Completions

The CLI supports auto-generated shell completions via Click:

# Bash - add to ~/.bashrc
eval "$(_WTF_COMPLETE=bash_source wtf)"

# Zsh - add to ~/.zshrc
eval "$(_WTF_COMPLETE=zsh_source wtf)"

# Fish - add to ~/.config/fish/completions/wtf.fish
_WTF_COMPLETE=fish_source wtf | source

Or generate completion scripts via make completions-bash, make completions-zsh, or make completions-fish.

Versioning and Releasing

Version bumping, tagging, and publishing are documented in RELEASE.md.

Quick reference:

make version       # Show current version
make bump-patch    # Bump patch version
make release       # Commit and tag (run bump-* first, then push)

Dual Functionality

This package supports two usage patterns:

1. Standalone script (via uv shebang):

   ./wtf --help

   Dependencies are automatically installed from inline metadata.

2. Installed package (via PyPI):

   pip install worktreeflow
   wtf --help
   # or
   worktreeflow --help

   Dependencies are installed from pyproject.toml. Both wtf and worktreeflow commands are available after installation.