git-claw logo

git-claw cheatsheet 🦀

A visual, interactive cheatsheet for deterministic Git Worktrees orchestration.

About & Core Concepts

Parallel human and AI workspaces without port conflicts or workspace collisions.

Isolation Model
Dedicated Worktrees & Deterministic Slots
Instead of in-place branch switching (`git checkout`), every branch lives in its own directory:
  • Deterministic Slot ID: Sequential numeric slot (1, 2, 3...) allocated per worktree.
  • Port Offsets: Effective Port = Base Port + Slot ID.
  • Environment: Auto-generates .env.worktree in each workspace.
  • Shared Caches: Transparent symlinks for node_modules, target, .venv.
$git claw feature start auth-jwt
→Assigned Slot 1 (Web: 8001, DB: 5433)
→Created ../my-app-worktrees/auth-jwt

Setup & Installation

Install the binary and configure shell auto-completions.

Installation via Cargo
Install directly from crates.io or compile from source. Git registers git-claw automatically as git claw.
$cargo install git-claw
$git-claw --version
Shell Auto-Completion
Generate native auto-completion rules for Fish, Bash, or Zsh.
$git claw completion fish > ~/.config/fish/completions/git-claw.fish
$git claw completion bash > ~/.local/share/bash-completion/completions/git-claw
$git claw completion zsh > ~/.zfunc/_git-claw

Getting Started

Zero configuration out of the box, with optional project tailoring.

Initialize Repository (.git-claw.toml)
Interactively configure base ports, hooks, and shared cache directories. Pass -y to accept inferred defaults.
$git claw init
$git claw init --yes

Features

Develop new features branched off main in fully isolated workspaces.

Start a new feature
Creates branch feature/<name>, allocates a unique Slot ID, generates .env.worktree, and symlinks shared caches.

Flag --isolated: skips shared cache symlinking.
$git claw feature start auth-flow
$git claw feature start auth-flow --isolated
Work inside a feature
Open in your default editor (VS Code, Cursor, $EDITOR) or execute commands directly inside the worktree with environment variables loaded.
$git claw open auth-flow
$git claw run auth-flow npm run dev
$claw cd auth-flow
Publish a feature
Pushes the feature branch to remote (origin) with upstream tracking. Auto-infers the branch when executed inside the worktree directory.
$git claw feature publish auth-flow
$git claw feature publish
Finish up a feature
Executes pre-finish test hooks (blocks merge if failing), merges into main, deletes worktree directory, deletes local & remote branches, and reclaims Slot ID.

Flag --keep-remote: preserves remote branch.
Flag --force: bypasses hook failures.
$git claw finish auth-flow
$git claw finish auth-flow --keep-remote

Bugfixes & Hotfixes

Standard fixes and urgent production patches.

Bugfixes & Hotfixes Workflow
Standard bugfixes branch off main. Hotfixes are reserved for critical production repairs. Both share identical lifecycle commands.
$git claw bugfix start fix-session
$git claw hotfix start security-patch
$git claw finish security-patch

Spikes (Disposable POCs)

Experimental exploration intended to be discarded without merging.

Create and Drop Spikes
Spikes create a temporary workspace on spike/<name>. Dropping safely destroys the directory, deletes the branch, and releases the Slot ID.
$git claw spike start vector-db
$git claw spike drop vector-db

Releases (SemVer & Changelog)

Automated Commitizen-style releases and manifest synchronization.

Automated Conventional Commit Tagging
Run on a clean main branch without arguments:
  • Infers SemVer bump (Major: feat!:, Minor: feat:, Patch: fix:).
  • Generates/updates CHANGELOG.md grouped by category.
  • Updates Cargo.toml (Rust) or pyproject.toml / project.toml (Python/uv).
  • Synchronizes lockfiles (Cargo.lock, uv.lock).
  • Commits chore: release <version> and tags main.
$git claw tag

# Explicit version override:
$git claw tag v1.2.0

Commands Quick Reference

Complete syntax table for all git-claw actions.

Command Action
git claw init [-y] Initialize or update repository configuration
git claw list Display active worktrees, assigned slots, and ports
git claw feature start <name> Create and start isolated feature worktree
git claw publish [<name>] Push worktree branch to remote with upstream tracking
git claw finish <name> Verify tests, merge into main, delete branch, and cleanup
git claw spike start|drop <name> Create or discard disposable experiment worktree
git claw open|run|cd <name> Workspace editor open, command execution, or path navigation
git claw tag [<version>] Commitizen auto bump or explicit release tag
git claw completion <shell> Generate shell auto-completion script