Skip to content

README.md

Latest commit

 

History

History
220 lines (160 loc) · 5.21 KB

README.md

File metadata and controls

220 lines (160 loc) · 5.21 KB

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:

  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.