GitTwin

Run multiple git commits, branches, or tags of the same application side by side, each in its own isolated environment — for comparison, debugging, regression testing, and demonstrations.

Status: early / pre-alpha. The pipeline described below is the design target; the CLI is just getting started.

Why

Reproducing "it worked on commit X but not on commit Y" usually means stashing changes, checking out refs one at a time, and juggling ports, dependencies, and env files by hand. GitTwin is meant to make that a single command:

1. Point it at a repo and a list of refs (commits, branches, or tags).
2. It spins up an isolated environment — its own worktree, dependencies, and ports — for each ref.
3. You run, compare, and debug them side by side, without one checkout clobbering another.
4. Tear it all down in one command when you're done.

Install

uv add gittwin
pip install gittwin

Usage

gittwin about
gittwin --version
gittwin doctor   # checks git and uv are installed and on PATH
gittwin list     # lists worktrees gittwin has created in the current repo

How worktrees work

gittwin checks out each ref you want to run into its own git worktree — a separate working directory sharing the same .git history, so multiple refs can be checked out side by side without one clobbering another or disturbing your current branch.

• Worktrees are created under <repo>/.gittwin/worktrees/<ref> by default.
• gittwin list shows only worktrees gittwin created — your main checkout is never listed as one of them.
• Any ref shape works — commit SHA, branch name, or tag — and an invalid ref fails immediately with a clear error instead of a raw git traceback.
• If setup for a ref fails partway through, gittwin removes that worktree again rather than leaving a half-provisioned one behind.

This is the foundation gittwin run/gittwin compare (coming soon) will build on: an isolated environment, dependencies, and a port per worktree.

Development

This project uses uv for dependency management.

uv sync --extra dev   # install package + dev deps into .venv
uv run pytest -q      # run tests
uv run gittwin about  # run the CLI