# Git status to a lossless JSON change manifest

Use this when an agent needs a structured working-tree snapshot before reviewing a patch. Paths containing spaces, tabs, line breaks, or non-UTF-8 bytes must not become different filenames.

Download the bundle from https://execution-evidence-lab.tuned-drake-1114.chatgpt.site/resources/git-status-json/bundle.zip and extract it into a separate local directory. Read the scripts before running them. The utilities send no network requests.

## Run

Python 3 standard library. The live adapter additionally requires Git. In the repository you intend to inspect, run Python with the absolute path to the extracted `from_git.py`:

```sh
python /absolute/path/to/git-status-json/from_git.py
```

The adapter runs `git --no-optional-locks status --porcelain=v2 -z --untracked-files=all`, waits at most 30 seconds, checks its exit code, then converts at most 1 MiB of status bytes. Git failure is an error, never a clean working tree. A temporary status spool is removed after use. It does not stage, commit, or modify repository files.

To inspect already captured porcelain-v2 **NUL-delimited bytes**, use a POSIX-compatible shell:

```sh
python convert.py < example.status.bin
python test.py -v
```

`example.expected.json` is the recorded output for that synthetic input. `verification.json` records the executed tests, runtime, timestamp, and source hashes. The test suite creates and removes its own temporary Git repository; it does not modify your repository.

## Output contract

- `ok: true` means the supplied status stream was converted, not that the repository is safe or clean.
- `records` distinguishes ordinary, rename/copy, unmerged, untracked, and ignored entries.
- Tracked entries retain index/worktree `xy`, submodule flags, modes, and object IDs as reported.
- Every path includes authoritative `bytes_base64` and `utf8` display text. `utf8` is null if strict UTF-8 decoding fails. Use the byte field when preserving exact filenames.
- Renames/copies include `original_path`. The destination is the record's `path`.
- Unknown headers are counted and ignored. Unknown data records, missing NUL terminators, truncated rename pairs, and oversized inputs fail explicitly.

Exit 0 means conversion succeeded; exit 1 means failure. Diagnostics are JSON. An empty supplied stream yields an empty snapshot; only `from_git.py` also verifies that Git succeeded.

## Limits and source

This is one status snapshot, not a diff, file-content reader, identity check, or complete Git-format validator. Git configuration and command options affect ignored files, submodules, and rename detection. Do not infer absent file contents or a future unchanged state. Command examples use Python 3; the tested runtime is recorded in `verification.json`, and other runtimes remain unverified.

Format reference checked 2026-09-10: [Git porcelain version 2](https://git-scm.com/docs/git-status#_porcelain_format_version_2). Original utility code and fixtures: MIT, see `LICENSE`.