worktreeflow 0.3.3

Git workflow manager for feature branches using worktrees, shows you cli equivalent commands

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.