# vcs-status

Pi workspace VCS telemetry for Git and Jujutsu.

## Install / load

Loaded through root `pi-ext` package.
See [root README](../../README.md).

## Commands / tools / settings

- Pi commands:
  none
- Pi tools:
  none
- Settings:
  `vcs-status.timeoutMs`, see [Settings](#settings)
- Hooks:
  `session_start`, `agent_end`, `tool_execution_end`, `session_shutdown`
- Pi events:
  - emits `footer:segment` when `@bugabinga/pi-ext-footer` is loaded
- External commands:
  - `git status --porcelain=2 --branch`
  - `git rev-parse --verify --quiet refs/stash`
  - `jj -R <root> --ignore-working-copy --no-pager --color never log --no-graph
    -r @ -T <json-template>`

## Behavior

Shows current working directory and VCS identity/status in UI sessions.
The cwd label collapses `$HOME` to `~`.

Detection:

- walks from `cwd` to filesystem root
- detects colocated `.jj` + `.git` as `jj`
- detects plain Git through `.git` dirs/files, conventional bare `.git` dirs,
  and `$GIT_DIR`
- detects jj-only repos through `.jj`
- prefers Git over jj-only when a parent Git repo appears first

Git branch comes from the detected Git dir `HEAD`.
Dirty/ahead/stash status comes from porcelain v2.
Detached HEAD shows `HEAD`.

Jujutsu status comes from `jj log -r @` with `--ignore-working-copy`, so refresh
does not snapshot the working copy.
It shows current change id, local bookmarks, and flags:

- `∅` empty change
- `×` conflict
- `≈` divergent

If `jj` is missing in a detected jj repo, the VCS label is `?`.
Other jj command failures suppress the VCS label.

Git indicators:

- `=` conflicted
- `$` stash exists
- `✘` deleted
- `»` renamed
- `!` modified
- `+` staged
- `?` untracked
- `↑` ahead
- `↓` behind
- `⇕` diverged

With `@bugabinga/pi-ext-footer` loaded, emits `footer:segment` entries:

- `cwd`, zone `workspace`, order `0`
- `vcs`, zone `workspace`, order `1`

Without footer support, falls back to Pi status text keys:

- `cwd`
- `vcs`

When footer support is present, old `cwd` and `vcs` status text keys are cleared
before footer segments are emitted.
Without footer support, footer segments are cleared before status text is set.

Non-VCS dirs show cwd only.
Status refreshes on session start, agent end, and tool execution end.
Git and jj status commands time out after `vcs-status.timeoutMs`, default 2500 ms.
Segments/status keys are cleared on session shutdown.

## Settings

| Key | Env | Default | Valid |
| --- | --- | --- | --- |
| `vcs-status.timeoutMs` | `PI_VCS_STATUS_TIMEOUT_MS` | `2500` | integer ms from `1` to `2147483647` |

Timeout for the `git status` and `jj log` status commands.
Example `settings.json`: `{ "vcs-status": { "timeoutMs": 5000 } }`.
Precedence: env, trusted project `.pi/settings.json`, user `~/.pi/agent/settings.json`, default.
Project settings apply only when the project is trusted.
Settings values must be JSON numbers; the env var accepts numeric strings.
Resolved once per session start.
An invalid value warns once and uses the 2500 ms default; it never falls through to a lower source.

## Debug

Opt-in metadata diagnostics: [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `status.refresh.start`, `status.refresh.finish`, `status.refresh.error`.