specs/015-gerrit-style-patchsets/contracts/cli.md

Ref: Size: 2.8 KiB
# CLI Contract: Patch Revisions

## Modified Commands

### `patch create`

No CLI changes. Internally records revision 1 (commit + tree OID) in the PatchCreate event.

### `patch revise <id> [--body <text>]`

Repurposed: now appends a `PatchRevision` event instead of `PatchRevise`.

- Resolves current branch tip, compares to last recorded revision
- If changed: appends `PatchRevision` with commit OID, tree OID, and optional body
- If unchanged: exits with error "no changes since revision N"
- Exit code: 0 on success, 1 on error

### `patch comment <id> --body <text> [--file <path> --line <n>] [--revision <n>]`

New optional flag: `--revision <n>`

- Without `--revision`: anchors to the latest revision
- With `--revision N`: anchors to revision N (error if revision N doesn't exist)
- Thread comments (no `--file`/`--line`): `--revision` is rejected ("thread comments are not revision-scoped")

### `patch review <id> --verdict <v> --body <text> [--revision <n>]`

New optional flag: `--revision <n>`

- Without `--revision`: anchors to the latest revision
- With `--revision N`: anchors to revision N (error if revision N doesn't exist)

### `patch show <id> [--json] [--revision <n>]`

New optional flag: `--revision <n>`

- Without `--revision`: shows all inline comments/reviews grouped by revision
- With `--revision N`: filters to show only inline comments and reviews from revision N
- Thread comments always shown regardless of `--revision` filter
- JSON output includes `revisions` array and `revision` field on inline comments/reviews

### `patch diff <id> [--revision <n>] [--between <n> [<m>]]`

New flags: `--revision <n>` and `--between <n> [<m>]`

- No flags: existing behavior (merge-base diff against current branch tip)
- `--revision N`: diff between merge-base and revision N's tree (historical full diff)
- `--between N M`: interdiff between revision N and revision M trees
- `--between N`: shorthand for "revision N to latest revision"
- `--revision` and `--between` are mutually exclusive (error if both provided)
- Error if referenced revision doesn't exist

## New Command

### `patch log <id> [--json]`

Lists all revisions of a patch.

**Default output** (human-readable):
```
Revision 1  abc1234  2026-03-21 10:00  (initial)
Revision 2  def5678  2026-03-21 14:30  +2 -1 files changed  "addressed review feedback"
Revision 3  ghi9012  2026-03-21 16:45  +1 files changed
```

**JSON output** (`--json`):
```json
[
  {
    "number": 1,
    "commit": "abc1234...",
    "tree": "...",
    "timestamp": "2026-03-21T10:00:00Z",
    "body": null,
    "files_changed": null
  },
  {
    "number": 2,
    "commit": "def5678...",
    "tree": "...",
    "timestamp": "2026-03-21T14:30:00Z",
    "body": "addressed review feedback",
    "files_changed": { "added": 2, "removed": 1 }
  }
]
```

Exit code: 0 on success, 1 if patch not found.