Edit several Format files in one commit with a change set

To edit several files of a Sume Format in one commit, send one PUT to /v1/formats/{handle}/{slug}/contents with a files list and no path. The API writes every file as a single commit, with one version increase and one new package_sha. If any entry has a stale sha or breaks a package rule, it commits nothing.

That all-or-nothing behavior, plus two surprises (the list is a change set, and it cannot delete), is what this post covers. Everything here comes from Format contents API.

One round trip instead of many

Writing one path at a time costs one commit and one request per file, and leaves the package in a half-edited state between calls. The batch form removes both costs. Each entry follows the single-file rules: content is the full file in base64, and sha is required when the path already exists. To create a path, leave sha out.

A change set is not the package

The docs are explicit that files is a change set. If the Format holds a path and your body does not name it, the API keeps that file as it is. An edit to two of twelve files never puts the other ten at risk, which also means you cannot remove a file by leaving it out. Use DELETE …/contents/{path} with the file's sha, and it removes the file only when you ask.

This is the opposite of a typical sync tool that makes a folder match a source tree. If your repo is the source of truth, diff the Format's file list against it and send deletes yourself.

Guard the whole package with If-Match

A per-file sha cannot say that the package has not moved since you read it. Two writers can edit different files, each holding a current sha, and both writes land, although the second plan was made against an old tree. Send the package sha as If-Match: it is commit.tree.sha from your last write and the same value as package_sha on the Format record.

If the package changed, you get 409 format_package_sha_mismatch, and error.details.package_sha holds the current value, so a read-and-retry takes one round trip. It is a bare 40-character hex string, not an opaque ETag. Formats published before package_sha existed ignore the header instead of returning a 409 you can never satisfy.

A safe edit routine

Combine the pieces in this order.

• Lint the folder locally against the package rules.
• Read the Format record and keep package_sha and each file's sha.
• Send one PUT with If-Match, a message, and only the files that changed.
• On format_package_sha_mismatch, re-read, re-plan the edit, and send again.
• Send a DELETE for each file you removed, and carry the new package_sha into the next call.