fork3 0.2.2

Manage parallel branch workspaces around git repositories

中文

fork3

Run multiple parallel attempts at the same coding task — without juggling branches manually.

Motivation

You're working on a feature. You have an idea, but you're not sure which approach will work best. So you want to try two or three implementations side by side — each in its own isolated copy of the repository, each on its own branch, all tracked together.

Without fork3, this means manually cloning, creating branches, remembering which copy is which, and pushing them all one by one. It's tedious, error-prone, and clutters your workflow.

fork3 automates this entire workflow:

• Point it at a repository and tell it how many parallel copies you want
• Each copy gets its own feature branch, ready for independent work
• All copies share the same remote — no extra setup
• When you've picked a winner, sync the others to match in one command

If you frequently explore multiple approaches before committing to one, fork3 removes the friction from that process.

Quick Start

pipx install fork3

fork3 ./my-project -n 3

fork3 st

fork3 push

fork3 sync branch2

That's it. Five commands take you from zero to a fully managed parallel workspace:

1. Install fork3 via pipx
2. Create 3 parallel copies of ./my-project
3. Check status of all copies
4. Push all branches to remote
5. Sync all copies to the branch2 winner

Installation

Install with pipx (recommended for CLI tools):

pipx install fork3

Or with uv:

uv tool install fork3

Or with pip:

pip install fork3

Requirements: Python 3.11+ and Git.

CLI Reference

Command	Arguments	Flags	Description
fork3 create	REFERENCE_REPO	-n N (default 3, min 2), --uv, -l ID	Create parallel copies of a repository
fork3 init	REFERENCE_REPO	-l ID	Adopt an existing layout as a workspace
fork3 push	—	-l ID, --dry-run	Push all copies to remote
fork3 sync	COPY	-l ID, --dry-run, --no-push, --force	Sync all copies to a chosen winner
fork3 fetch	—	-l ID	Fetch latest changes for all copies
fork3 status / st	—	-l ID	Show status of all copies

Shorthand: fork3 ./path -n 3 is equivalent to fork3 create ./path -n 3. Any path-like first argument triggers an implicit create.

Flag details:

• -n, --copies N — Total number of copies including the original (minimum 2, default 3)
• --uv — Replicate uv-based virtual environment into new copies
• -l, --lineage ID — Specify workspace ID explicitly (auto-detected if omitted)
• --dry-run — Print the operation plan without executing
• --no-push — Reset locally without force-pushing to remote
• --force — Override dirty-copy safety check

Run fork3 <command> --help for full details on any command.

How It Works

fork3 manages a workspace — a group of parallel copies of the same repository, each on its own branch.

When you run fork3 create ./my-project -n 3, fork3:

1. Clones your repository twice (the original counts as copy #0)
2. Creates a unique feature branch in each clone (e.g. fork3/my-project/1)
3. Records the workspace layout in a .fork3/ directory at the parent level

The result looks like this:

parent-dir/
├── my-project/          ← your original repository (unchanged)
├── my-project_fork1/    ← copy 1 (branch: fork3/my-project/1)
├── my-project_fork2/    ← copy 2 (branch: fork3/my-project/2)
└── .fork3/              ← workspace metadata

Each copy is a full git clone sharing the same remote. You work on each copy independently — different approaches, different experiments, no conflicts.

Typical Workflow

create → work independently → status → push → sync (when ready)

1. Create — Set up your parallel workspace with fork3 create
2. Work — Develop different approaches in each copy
3. Status — Check progress across all copies with fork3 st
4. Push — Push all branches to remote with fork3 push
5. Sync — When you've picked a winner, run fork3 sync <copy> to converge

After syncing, all copies point to the same winner branch. The workspace stays intact — run create again to start a new round of parallel work.

Auto-Detection

fork3 auto-detects your workspace from any copy directory by walking up the directory tree to find the .fork3/ metadata. You don't need to specify -l in most cases — just run commands from inside any copy.

The --uv Flag

If your project uses uv for virtual environment management, pass --uv during creation. fork3 will replicate the virtual environment into each new copy so every workspace is ready to run immediately.

fork3 create ./my-project -n 3 --uv

Contributing

Contributions are welcome. See the developer guide for setup instructions and contribution guidelines.

License

This project is licensed under CC BY-NC-ND 4.0.

Copyright © Cheng Yanru