# Git context

Inspect git changes, history, churn, and file-level co-change. Shared flags on
the summary commands (`capture` takes only `--path`, `--ref`, and its bounds):
`--path <repo-root>` (default cwd), `--base <ref>`, `--head <ref>`, `--staged`,
`--range-mode merge-base|exact` (default `merge-base`; `exact` diffs the
endpoints directly instead of from the common ancestor), `--format
tabular|json`, `-o <file>`. Machine JSON is compact by default; the global
`--pretty` flag indents it. The diff range is resolved from
`--base`/`--head`/`--staged` (defaults to the working-tree changes when
unspecified).

## `occ git capture`

Stream immutable, machine-first repository evidence. Unlike the summary commands below, capture walks every commit reachable from the resolved ref, preserves all parents, includes every pinned-tree path, and emits only NDJSON.

```bash
occ git capture --path . --ref HEAD
```

Read the final footer before accepting the stream. A fired `--max-commits`, `--max-changes`, or `--max-tree-entries` bound, shallow history, missing objects, or a Git failure makes coverage incomplete. Blob bodies are addressed by OID and are not embedded. `--batch-size`, `--max-record-bytes`, and `--timeout-ms` tune resource limits without changing the evidence model. Add `--require-complete` to preserve the stream while making an incomplete footer exit nonzero.

## `occ git changed`

List changed files for the resolved diff range — a quick scope check.

```bash
occ git changed --path .
occ git changed --base main --format json
```

## `occ git diff`

Summarize the resolved diff, or render it as a bounded patch.

```bash
occ git diff --format json                              # summary (files, +/- counts)
occ git diff --patch --map-tokens 2048 --tokenizer o200k_base   # raw patch, token-bounded
```

Flags: `--patch` (raw unified diff instead of summary), `--map-tokens <n>` +
`--tokenizer` to cap patch size.

## `occ git history [file]`

Show commit history for a range or a file (hash, author date, subject).

```bash
occ git history src/cli.ts --limit 10
occ git history --since 2025-01-01 --format json
```

Flags: `--limit <n>` (default 50), `--since <date>`, `--scope range|history`
(default range; `history` logs full HEAD history — the default diff range is
empty on a clean tree sitting on its base branch), `--follow` (track renames),
`--line-start <n>` / `--line-end <n>` (for `git log -L` line history). Per-file
history always logs full HEAD history.

## `occ git churn`

Rank changed files by churn — find hotspots worth attention.

```bash
occ git churn --sort churn --limit 20 --format json
```

Flags: `--sort churn|commits|added|deleted|net` (default churn), `--limit <n>`,
`--since <date>`, `--scope range|history` (pair `history` with `--since` for a
windowed hotspot ranking over full HEAD history).

## `occ git cochange`

Rank file pairs that historically change together. Use this for file-level
blast-radius hints before editing a known path.

```bash
occ git cochange --limit 20 --format json
occ git cochange --target src/cli.ts --format json
occ git cochange --since 2025-01-01 --max-commit-files 30
```

Flags: `--limit <n>`, `--since <date>`, `--scope range|history` (pair `history`
with `--since` for co-change over a real history window), `--target <path>`,
and `--max-commit-files <n>` (default 50). JSON pairs include `fileA`, `fileB`,
`count`, `lift`, and `lastCochangedAt`. Co-change is file-level only; use
`occ code diff` for symbol-level changed-code context. `--scope history`
rejects `--base`/`--head`/`--staged` (same rule on history/churn).

## Symbol-level changes

To see which _symbols_ (not just files/lines) changed, use `occ code diff`
(see [code.md](code.md)).
