diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 8abba4fe..f2de77a0 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -21,6 +21,7 @@ The read-only commit endpoints inspect the stored `.mwp` on the server. Clients - `state`: what running the project changes rather than edits. That is variable and list values, sprite position, size, direction, layer and visibility, stage settings, the current costume, monitors and where scripts sit on the canvas. Reordering scripts or moving them on the canvas, a newer Fractch spelling of the same block (also inside `${...}` in template strings), a value hidden under a reporter, and rotation centres that differ by less than 0.005 are not reported as edits. Other files are listed in `files` like the plain endpoint with inline text. `totals` counts everything, and `totals.stateOnly` is true when saved state is all that changed. A sprite with a region file over 1 MiB, or whose region files together pass what is left of the 8 MiB response budget, is listed with `tooLarge: true` and no breakdown. Renaming a sprite renames its folder, so it shows as one target removed and another added. `GET /v1/projects/:id/pulls/:index/diff?view=changes` returns the same shape for a pull request in `inspection`. +- `GET /v1/projects/:id/commit-summaries?shas=,` returns a short summary for each listed commit, for commit lists. It uses the same access rule as `/commits/:sha/changes`, without the pull request exception. It takes up to 50 lowercase hex SHAs and ignores any that are malformed, repeated, or not recorded by the project. Commits that cannot be summarised (for example when the parent commit is missing) are left out of `summaries`. Each entry in `summaries` (keyed by SHA) has `totals` (the same counts as the changes view, comparing a merge commit with its first parent), `sprites` (the names of up to five sprite folders with script, item or asset changes; saved state alone does not name a sprite, and `fonts/` or root `assets/` files are counted in `totals` but name no sprite), `spriteCount`, `authoredFiles` (changed files that are not sprite code, assets or `fractch.json`), `tooLarge` (true when a sprite was too large to compare), `legacy`, and `initial` (true for a commit with no parent). Summaries are computed the first time they are asked for and kept in one cache file per project under `git-summaries/` in the temp directory, so saving the project does not recompute them. A project with no recorded branch heads returns an empty `summaries` object. Failures are cached for ten minutes. The file holds up to 2,000 entries and starts again from the current request when new entries would push it past that. The cache name carries its own version, which changes whenever the summary format does. - `GET /v1/projects/:id/commits/:sha/tree` returns `commit` and a flat `files` array. Each file has `path`, `oid`, `mode`, `size`, and `binary`. - `GET /v1/projects/:id/commits/:sha/file?path=` returns one file record and `content`, encoded as base64 by JSON. - `GET /v1/projects/:id/commits/:sha/co-authors` returns the Rotur users credited on that commit. The older `/collaborators` path remains an alias.