Metadata-Version: 2.4
Name: gitgrip
Version: 2.0.0a9
Summary: Workspace layer for multi-repo work: workspaces, isolated lanes, and one grouped review per slice
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9
Requires-Dist: tomli_w>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: toml>=0.10
Requires-Dist: jsonschema>=4.18
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: packaging>=22; extra == "dev"

# gr2

**gr2 is the workspace layer for multi-repo work.** One repository is just git; when a change spans repositories — a feature slice, a release, several agents touching several repos — gr2 gives you a workspace over them, isolated lanes to work in, and one grouped review/PR set for the slice. It is the Python successor to the Rust `gr` (1.x, called gr1 below); both ship from this repository, and `gr2` is the command for the workspace and the slice.

## Install

```bash
uv tool install --pre gitgrip    # the PyPI package is "gitgrip"; it installs `gr` and `gr2`
gr2 --version
```

Without uv, a venv and pip do the same:

```bash
python3 -m venv ~/gr2-venv && source ~/gr2-venv/bin/activate
pip install --pre gitgrip
gr2 --version
```

`--pre` is required while every gr2 release is an alpha: 1.5.0 and 1.5.1 were pre-alpha builds and are yanked, so without `--pre` there is nothing to install.

Already installed 1.5.0 or 1.5.1? The install commands above leave it in place, because an installed version already satisfies them. Upgrade explicitly: `uv tool upgrade --prerelease allow gitgrip`, or `pip install --pre -U gitgrip`. To run unreleased development code instead, install from a checkout: `pip install -e gr2/` from the repository root.

The package installs two commands. `gr2` always runs gr2. `gr` picks by the nearest workspace marker: in a gr1 workspace (`.gitgrip`) it runs gr1, and anywhere else, including outside any workspace, it runs gr2.

The Rust `gr` (gr1, 1.x) installs with `brew install synapt-dev/tap/gitgrip` or `cargo install gitgrip`, as `gr` and `gitgrip`. You can have both installed. Whichever `gr` comes first on `PATH` answers: gitgrip 1.5 and earlier always run gr1, so if it comes first, type `gr2` for gr2 (`gr2` says so once). In a gr1 workspace, this package's `gr` runs gr1 through `gitgrip`. With no gr1 installed, it serves a workspace already moved with `gr2 workspace migrate-gr1`, and in one not yet moved it says how to move it.

## First five minutes

Every command below was run, in this order, in a clean virtualenv against a throwaway workspace of two repositories. Put two clones side by side in one folder, say `~/ws/repo-a` and `~/ws/repo-b`.

```bash
cd ~/ws
gr2 workspace init ~/ws                 # scans the folder; writes .grip/workspace_spec.toml
gr2 workspace materialize ~/ws --yes    # builds the .grip layout and a default unit
gr2 workspace status ~/ws               # what kind of workspace this is
gr2 store init ~/ws                     # the workspace snapshot store (needed before review)
```

A **unit** is one worker — you, or one agent — and `default` is created for you. A **lane** is one piece of work spanning repos, with its own clones, so two lanes never step on each other:

```bash
gr2 lane create ~/ws default feat-x --repos repo-a,repo-b --branch feat/x
gr2 lane enter  ~/ws default feat-x --actor human:you
```

Both commands print, per repo, the absolute directory you work in:

```
repo-a: ~/ws/.grip/state/lanes/default/feat-x/repos/repo-a
repo-b: ~/ws/.grip/state/lanes/default/feat-x/repos/repo-b
```

Edit there — not in your original clones. Stage and commit across the lane's repos:

```bash
gr2 add . --repo-path ~/ws/.grip/state/lanes/default/feat-x/repos/repo-a
gr2 commit -m "my change" --workspace-root ~/ws --owner-unit default
```

`commit` with the lane flags commits every lane repo that has staged changes and names the repos it skipped. If every repo was skipped it exits non-zero with one sentence naming where it looked — and, when it can see them, where your staged changes actually are. Run one command across every lane repo, then turn the lane into one reviewable object:

```bash
gr2 exec run ~/ws default --actor human:you -- pytest -q   # one command, every lane repo
gr2 review create-project ~/ws default feat-x              # prints gr:<sha>: one object to review
gr2 lane push ~/ws default feat-x                          # push every lane repo, each verified on its remote
gr2 lane show ~/ws default                                 # where am I?
gr2 lane exit ~/ws default --actor human:you
gr2 lane list ~/ws                                         # each lane: removable, or keep and why
gr2 lane remove ~/ws default feat-x                        # end it: its clones and record go
```

`lane remove` refuses while the lane is entered or leased, or was made by `lane bind`, while any of its repos holds uncommitted work, a stash, or a commit no remote has (on any branch or tag), or while its checkout holds anything that is not one of its repos; it names each one and removes nothing. `exec run` and `lane exit` require `--actor`. Every group and verb takes `--help`; `gr2 --help` lists them all.

## What works today, and what is not there yet

Alpha 2 is a working local workspace layer. Verified by running the walk above:

- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, commit, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
- Lanes are independent clones: two lanes, or two agents, never share refs, an index, or a working tree.
- A lane commit that commits nothing anywhere refuses loudly instead of reporting success.

Not there yet:

- The full walk with **remote** PRs (`gr2 push`, `gr2 pr create`) is documented in `--help` but was not exercised in a clean environment for this README; treat those two as alpha.
- `gr2 --help` and some verb output still say "prototype" in places; the wording is being cleaned up as verbs land.
- The Rust `gr` (gr1) still owns `spawn`, `fleet`, and `manifest` until their gr2 ports land. Everything else — workspace sync, lanes, the multi-repo slice, its review — is gr2's job; if a verb is missing or wrong there, that is a bug worth reporting, not a reason to reach for gr1.

## Commands

| Group | Verbs |
|---|---|
| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, retire-gr1, migrate-lane-state, bootstrap-gr1, gitinclude |
| `spec` | show, validate |
| `lane` | create, enter, exit, show, resolve, bind, lease, list, push, remove |
| (top level) | branch, add, commit, push, prune, status, plan, apply |
| `sync` | status, run |
| `pr` | create, status, checks, merge, view |
| `check` | run, show, set |
| `review` | open, close, checkout-pr, run, check, pin, publish, receive, verify, show, stamp, merge, repin, create-project, bind, approve, rebind |
| `exec` | status, run |
| `repo` | status, projection-run |
| `hooks` | trust, revoke, status, show, run |
| `store` | init, commit, check, push, status, log, diff, checkout, materialize, migrate, migrate-reviews |
| `target`, `config` | stored PR target; config overlays |

`review bind`, `review approve` and `review rebind` remain as aliases of `pin`, `stamp` and `repin`.

The words these commands use (lane, pin, stamp, repin, gate, review) are defined in [docs/GLOSSARY.md](docs/GLOSSARY.md).

## Stamps (unsigned approvals)

Inside a workspace with one pinned review matching every member's current head,
a reviewer stamps it as the workspace's Git `user.name`:

```bash
gr2 review stamp
gr2 review merge
```

The author recorded by the pin, and anyone who authored a commit in its range,
cannot stamp it. A stamp records an approval; approver names are self-declared and receipts say `signed: false`.
Repeated stamps by the same name count once. A moved head needs a new pin
and fresh stamps. Signing is not implemented by these commands.

The workspace's `grip.toml` sets the number required before merging:

```toml
[approvals]
required = 2
```

The default is zero; `review merge --approvals N` can raise the count for that
run, but cannot lower the workspace policy. With zero required, the merge gate
skips approval counting. When approvals are required, broken records or different
chain tips across member remotes refuse before this run pushes a merge. After a refused stamp, rerun
`review stamp` to read the current chain and retry with a lease.

## Overlay substrate

gr2 also carries the config-overlay substrate (capture, compose, and materialize configuration layers over a workspace): see [docs/OVERLAY-SUBSTRATE.md](docs/OVERLAY-SUBSTRATE.md).

## Development

```bash
pip install -e "gr2[dev]"    # from the repository root
cd gr2 && pytest             # the gr2 suite (tests + overlay tests)
cd gr2 && ruff check .       # lint, same config as CI
```

The Rust development binary is **`gr2-dev`** — built by `cargo build -p gr2-cli --release`, `publish = false`, and not shipped with `cargo install gitgrip`. It answered to the name `gr2` until 2026-09-30, so a branch written before that rename goes red on `cargo test -p gr2-cli` with `CARGO_BIN_EXE_gr2 is unset`; the repair is `cargo_bin("gr2-dev")`, from which Cargo derives `CARGO_BIN_EXE_gr2-dev`.

Migration: use `gr2 review check` for compiled review requirements. `review requirements`
remains a hidden alias with a warning on stderr until beta. Both report `satisfied`
in the same JSON payload, and a missing reviewer remains a reported status with exit 0.

A bare `gr2 review open <workspace>` uses the workspace's sole pinned review. Its default directory is `<workspace>.review/<sha8>` in the workspace's parent directory, and the command announces that path on stderr. Give `--lane-dir` to choose another location.

New pinned reviews record the author's Git `user.name` from the workspace root.
Set it with `git config user.name 'Your Name'` there if Git has no configured name.
`review show --json` and `review verify --json` include this author; older pinned reviews
remain readable without an author field, and reading them does not invent one.


## Transfer a native review

Publish an existing pinned review and receive it in another native workspace:

```bash
gr2 review publish gr:<full-review-id> --remote https://example.org/workspace.git
gr2 review receive gr:<full-review-id> --remote https://example.org/workspace.git
gr2 review show gr:<full-review-id>
gr2 review verify gr:<full-review-id>
gr2 review open gr:<full-review-id> --lane-dir /absolute/fresh-review
```

The root defaults to the current workspace. Use `-C /absolute/workspace` to override
it. Transport requires an independently supplied full 40-character lowercase
review ID and an explicit HTTPS URL or absolute local remote path. It does not
infer the expected ID from the remote. A review is published at
`refs/dev.synapt.grip/__reviews__/v1/<full-review-id>`; `--ref`, when supplied, must be
exactly that, or the older `refs/dev.synapt.grip/__reviews__/<full-review-id>`. Invalid explicit input is
refused without falling back to context.

Publish transfers only that review ref and confirms its returned target. Receive
compares both the advertised and actual fetched raw target with the expected ID,
requires a commit and recomputable review content, then creates the canonical
local review ref. A valid same-ID receive is idempotent. A conflicting existing ref
is refused. Object downloads may remain after refusal. The owned temporary ref
is removed separately, and cleanup failure is reported without replacing a
primary failure.

The review commit carries its trees, blobs and range patches. It does not make
its recorded base or original member head reachable as Git parents. Keep each
member's base reachable at its recorded remote for reconstruction. `verify`
checks content consistency, not current remote state, provenance or approval.
`open` checks reconstructed member trees. Commit identity can differ from the
original head. Receiving content grants no local approval, allocation, selection
or cleanup authority. Opening a reconstruction remains a separate operation.


## External PR adapters

External packages can expose a zero-argument factory through the
`gr2.platform_adapters` entry-point group. See [the adapter contract](docs/PR-LIFECYCLE.md#51-adapter-protocol-and-capabilities)
for registration, optional operation capabilities and merge head-pin requirements.
What changed in that protocol, release by release, ships in the package: read it from
an install with `importlib.resources.files("gr2") / "PLATFORM_ADAPTER_CHANGELOG.md"`,
or in this repository at [gr2/PLATFORM_ADAPTER_CHANGELOG.md](gr2/PLATFORM_ADAPTER_CHANGELOG.md).
Select the installed adapter with `gr2 pr create ... --platform NAME` on a
materialized lane. The bound-lane path currently pushes and returns its receipt.

PRs start as drafts by default. `--draft` is explicit draft creation, while
`--no-draft` explicitly creates non-drafts. The same default applies to
`CreatePRRequest` and `create_pr_group`. Existing Python callers can retain
non-draft creation with `draft=False`. Plugins execute trusted Python from the
existing environment. The CLI never installs or downloads them.

## Checks on a plain Git remote

Run a command at an exact full commit id in a disposable checkout, then publish
its exit status to the repository's remote:

```sh
gr2 check run ./repo -- python -m pytest
gr2 check show ./repo --json
```

With no flags, the remote is the current branch's upstream (else `origin`) and the head is `HEAD`,
as a full commit id. gr2 prints what it resolved on stderr. `--remote` (a URL, an absolute path or a
remote's name), `--head` and `--name` override them. With no upstream and no `origin`, it refuses and
asks for `--remote`.

Absolute paths to local bare remotes also work. Observations live at
`refs/dev.synapt.grip/__checks__/v1`, keyed by commit id. `check show` fetches a
fresh snapshot; a different commit has no check even when its tree is identical.
Supplied `--require` names replace the default `test` requirement. For both
checks, use `--require test --require lint`.

The read JSON contains `status`, `record_id` (the head's record-set blob id or
null), `snapshot_oid`, `head`, `member_key`, `records`, and `reason`. Each
observation retains its fields and adds a SHA-256 `observation_id`.

A review over several members is checked as one set. `gr2 check set <workspace> <review> -- <command>`
reconstructs every member at its pinned head side by side (`GR2_SET_ROOT`, `GR2_REVIEW_ID` and `GR2_SET_MEMBERS`
name them), runs the command once, and publishes one `set` observation per member remote, carrying the review and the
identity of the set. `gr2 review merge` requires that record on a multi-member review (`--no-set` says otherwise),
and `check show --require set --review <id>` reads a `set` record for another review as stale.

A failed command is recorded and `check run` exits 1. Publication or execution
refusals exit 2. `check show` returns `pass`, `fail` or `absent` in its JSON;
failed or unmeasurable reads exit 2. Conflicting pass and fail observations both
survive and refuse readiness. Rerunning a check does not erase its earlier
failure at that commit. Concurrent writes union observations with bounded
compare-and-swap retries. An unmeasurable push acknowledgement is reported as
indeterminate unless a fresh remote read confirms the observation.

## Merge a pinned review into plain Git remotes

```sh
gr2 review merge
```

This merges the review pinned at the members' current heads, from their current branch, into the
branch on each remote that still sits at the reviewed base, and prints what it resolved. If several
branches sit there, it asks for `--into`. It merges only if every member's remote feature
branch is still the reviewed head, the target is still the reviewed base, and the exact-head check
passes. If any member fails that preflight, nothing is pushed. Merges are separate pushes, not atomic
across repos: a member that moves after an earlier member was pushed is refused, and the run exits 4.

Exit codes:
- 0: all merged;
- 3: none merged (refused);
- 4: partial or unknown.

A review id, `--from` and `--into` override the defaults. Zero or several matching pinned reviews, or members on
different branches, refuse and name the value to pass.

These records are attestations by writers trusted with remote access, not signed
proof against a writer who can forge Git objects. Test output and environment
contents are not uploaded. Read this custom ref through gr2; plain `git notes`
cannot read notes outside `refs/notes/`.
