Formpatch

Handle Model

Each top-level object has:

• oid: stable file-local object identity encoded as a 6-character base62 token
• rev: short hash of the current full object text
• file_rev: short hash of the whole file

Default behavior:

• use oid to target an object
• append @rev when you want object-level optimistic locking
• pass --file-rev only when you need strict whole-file optimistic locking

This means one list can often support multiple follow-up edits without re-listing, as long as the target object itself has not changed.

Workflow

1. Run formpatch list --file <path> and inspect the returned JSON.
2. Pick the target object's oid; keep rev when you want a write guard.
3. If the preview is not enough to safely rewrite the full form, run get for the target objects.
4. Draft full replacement forms.
5. Prefer --dry-run --diff before mutating.
6. Run insert or replace.
7. Read the returned minimal mutation delta JSON and keep using the new file_rev, touched, before, and after handles instead of re-listing immediately.
8. Re-run list only when you need fresh discovery context, more full objects, or the mutation result does not give enough anchors.

Query

List top-level objects:

formpatch list --file src/foo/core.clj

Interpret the response as:

• file_rev: current file version
• oid: stable file-local 6-character base62 identity
• rev: optimistic lock for that object
• index: current position in the file
• text: truncated preview text
• text_truncated: whether the preview was truncated
• head / name: best-effort metadata for display and selection

Fetch one or more full objects:

formpatch get \
  --file src/foo/core.clj \
  --objects <oid>,<oid>@<rev>

Create

Insert new top-level forms with raw stdin.

Insert after an anchor object:

formpatch insert \
  --file src/foo/core.clj \
  --after <oid>@<rev> \
  --dry-run \
  --diff <<'EOF'
(defn helper-a
  []
  :a)

(defn helper-b
  []
  :b)
EOF

Remove --dry-run --diff to apply the edit.

Use --before instead of --after when needed.

Insert at the head of the file (no anchor needed):

formpatch insert \
  --file src/foo/core.clj \
  --head <<'EOF'
(ns foo.core)
EOF

Use --tail to append at the end of the file. Both --head and --tail work on empty files.

Successful insert returns minimal delta JSON including:

• file_rev
• touched
• deleted
• before
• after
• optional diff

Update

Replace one object by rewriting the full form:

formpatch replace \
  --file src/foo/core.clj \
  --targets <oid>@<rev> \
  --dry-run \
  --diff <<'EOF'
(defn updated
  [x]
  (inc x))
EOF

Replace one object with multiple objects by passing multiple top-level forms on stdin.

Replace multiple objects only when the target objects are contiguous in the current file.

If you need strict whole-file CAS, add --file-rev <file_rev>.

Delete

Delete with replace --empty:

formpatch replace \
  --file src/foo/core.clj \
  --targets <oid>@<rev> \
  --empty

Delete multiple objects only when the target objects are contiguous.

Deletion returns the removed oids in deleted.

Guardrails

• Prefer oid@rev for writes. Bare oid is convenient, but it will not protect you from overwriting a changed target object.
• Treat oid as file-local. Do not assume it is globally unique across files or repositories.
• Use --file-rev only when you truly need strict whole-file locking; otherwise it reduces handle longevity.
• Start with this skill only when Formpatch is the intended tool or is already available. Escalate to lower-level rewrite-clj work or another general editor when whole-object replacement is not sufficient or Formpatch is unavailable.
• Keep edits at top-level object granularity. If only part of a function changes, still replace the full function.
• Use --dry-run --diff before writing unless the change is trivial.
• Pass raw top-level forms through stdin. Do not wrap replacement code in JSON strings.
• Expect JSON on stdout for success and machine-readable JSON on stderr for failure.
• After a mutation, prefer the returned touched / before / after handles over an immediate extra list.
• When working inside this repository, prefer the repo-local entrypoint ./bin/formpatch. Outside repo development, prefer the installed formpatch command and do not probe ./bin/formpatch first.