Metadata-Version: 2.5
Name: gittwin
Version: 0.1.1
Summary: Run multiple git commits, branches, or tags of the same app side by side in isolated environments
Project-URL: Homepage, https://github.com/Shyam-Sundar-Reddy/GitTwin
Project-URL: Repository, https://github.com/Shyam-Sundar-Reddy/GitTwin
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
uv add gittwin
pip install gittwin
```

## Usage

```bash
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](https://git-scm.com/docs/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](https://docs.astral.sh/uv/) for dependency management.

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