specs/012-patch-branch-refactor/contracts/cli-commands.md

Ref: main   Size: 2.1 KiB

# CLI Contract Changes: Patch-as-Branch Refactor

## Modified Commands

### `git collab patch create`

**Before**:
```
git collab patch create --title "Fix bug" --base main --head abc123
```

**After**:
```
git collab patch create --title "Fix bug" --base main --branch feature/fix-bug
git collab patch create --title "Fix bug" --base main   # defaults to current branch
```

**Arguments**:
- `--title` / `-t`: Patch title (required)
- `--body` / `-b`: Patch description (optional, default "")
- `--base`: Target branch (optional, default "main")
- `--branch` / `-B`: Source branch (optional, defaults to current branch)
- `--head`: Deprecated alias for `--branch`, hidden from help
- `--fixes`: Issue ID this patch fixes (optional)

**Errors**:
- Current branch is the same as base → "cannot create patch from base branch"
- Active patch already exists for this branch → "patch already exists for branch '{name}'"
- Detached HEAD with no --branch → auto-creates branch `collab/patch/{short-oid}`

### `git collab patch show <id>`

**Output changes**:
```
Patch a89c37fa [open]
Title: Fix the bug
Author: dev <dev@example.com>
Branch: feature/fix-bug → main
Commits: 3 ahead, 0 behind (up-to-date)
Created: 2026-03-21T09:00:00+00:00
```

When outdated:
```
Commits: 3 ahead, 5 behind (outdated)
```

When branch deleted:
```
Branch: feature/fix-bug (not found)
```

### `git collab patch diff <id>`

**No argument changes**. Behavior change:
- Branch-based patches: shows three-dot diff (merge-base...branch)
- Old patches: unchanged behavior

### `git collab patch merge <id>`

**No argument changes**. Behavior change:
- Branch-based patches: merges branch into base (standard git merge)
- Old patches: unchanged behavior

### `git collab patch revise <id>`

**Behavior change**: Optional for branch-based patches. Can still be used to record a revision note. The `--head` flag is ignored for branch-based patches (branch tip is always used).

## Unchanged Commands

- `git collab patch list`
- `git collab patch comment`
- `git collab patch review`
- `git collab patch close`
- `git collab patch import` (creates a branch, then creates a branch-based patch)