geml

Reading and editing documents blockwise

Two jobs. The first is the common one, and it needs none of GEML's syntax.

A document that is NOT GEML — use this as a read layer

geml list, geml find and geml get read Markdown directly. Use them to locate and read one block of a long document. Nothing is converted, nothing is written, and the file stays exactly the Markdown it already was.

Only when you would otherwise read the whole file to change part of it. If the file is short, or you already know the exact string to replace, open it the ordinary way — the round trip costs more than it saves. What is saved is only ever the part you did not have to read: on this project's own docs a list map runs 5–11% of the file it maps, but on a changelog of many small sections it is 37%.

1. geml list <file> — every block: address, kind, line range.
2. geml find "<text>" <file> — which block holds those words, answered as an ADDRESS rather than a line number, so it survives the next edit. (On a file that is not .geml this needs 1.7.5 or newer; older builds report no match rather than an error, so if a search you expect to hit comes back empty, use list.)
3. geml get <file> '<address>' — that block and nothing else.
4. Change it. Two ways, and the choice is about consent, not capability:
   • Ordinary file-editing tool, using the text from step 3 as the string to replace. The default: a document nobody asked to address by block is edited the way its author edits it.
   • geml set <file> '#id' …, when block-addressed editing is what was asked for — a knowledge base, a generated index, a log that only grows. Measured on a real vault: the frontmatter and every block you did not address come out byte-for-byte unchanged, and the body you write lands verbatim — no escaping, no reflowing. Read references/markdown-writes.md first; two of its rules are silent when broken.