Metadata-Version: 2.4
Name: fork3
Version: 0.2.2
Summary: Manage parallel branch workspaces around git repositories
Project-URL: Homepage, https://github.com/chengyanru/fork3
Project-URL: Repository, https://github.com/chengyanru/fork3
Project-URL: Issues, https://github.com/chengyanru/fork3/issues
Author-email: Cheng Yanru <yanru@cyanru.com>
License-Expression: CC-BY-NC-ND-4.0
License-File: LICENSE
Keywords: branch,cli,git,workspace
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: tomli-w
Description-Content-Type: text/markdown

[中文](https://github.com/chengyanru/fork3/blob/main/README.md)

# fork3

[![PyPI version](https://img.shields.io/pypi/v/fork3)](https://pypi.org/project/fork3/)
[![Python](https://img.shields.io/pypi/pyversions/fork3)](https://pypi.org/project/fork3/)
[![License](https://img.shields.io/pypi/l/fork3)](https://creativecommons.org/licenses/by-nc-nd/4.0/)

**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

```bash
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](https://pipx.pypa.io/) (recommended for CLI tools):

```bash
pipx install fork3
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install fork3
```

Or with pip:

```bash
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](https://docs.astral.sh/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.

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

## Contributing

Contributions are welcome. See the [developer guide](https://github.com/chengyanru/fork3/blob/main/docs/developer-guide.md) for setup instructions and contribution guidelines.

## License

This project is licensed under [CC BY-NC-ND 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/).

Copyright © Cheng Yanru
