Publishing & fetching

A deployment serves one published revision at a time. Everything else you read is your draft. Under fs.local, and under fs.remote with disk: true or noemata up --edit, the draft is the files on disk, and the local server serves changes to them immediately. Shared workflows and other users read the published revision, so they see a change after you publish it. While a local server that drafts on disk runs, it writes each newly published revision to the files you haven’t changed. Your own changes reach the deployment only when you publish them.

Both commands connect to the deployment directly — no running server needed, just a checkout and, for a store, a reachable database. See Connecting to ClickHouse for which credentials they use, and why those differ from the ones your deployment serves requests as.

noemata publish

noemata publish publishes what changed in the working directory since you last fetched or published, compared by content: a file you edited or added replaces the published one, a published file you deleted leaves the tree, and every other published file is retained, including a file whose disk copy is older than the published one. Local files (*.local.*) and env files (.env, .env.*) never enter a revision, and the server serves neither env files nor the .data directory. Every frame is validated first, and nothing is published if any fails (--no-validate to skip that gate, --online to also render each one against live data). --dry-run lists the changes the revision would make without writing anything, and --message records why.

A file that changed both on your disk and in the deployment since you last fetched or published is a conflict. In a terminal, publish asks for each conflict whether to keep your version or take the deployment’s. Outside a terminal, publish refuses and lists the conflicts. --accept-ours or --accept-theirs resolves every conflict with one version. See Resolving conflicts. Publication replaces the head only if the head is still the revision the plan was made against. When someone else publishes in between, the publication is refused, and you can publish again.

A server publishes the signed-in user’s draft in the same way through POST /internal/deployment/publish. The route takes the options of noemata publish as message, dry_run, accept (ours or theirs), validate and online, and checks the user’s database credentials first. The response contains the outcome, the revision the deployment served (served), the published revision (published, or null for any other outcome), the changes, the conflicts, the draft’s local files, and every validation finding. Local files are never published. Without accept, a conflicting path is listed only under the conflicts. Under fs.remote without disk, the draft is the user’s changes in the store. Each change records the published version it started from, so a change made before someone else’s publication is also a conflict. GET /internal/deployment/status lists the draft’s changes, its conflicts with the latest revision, and its local files. POST /internal/deployment/resolve resolves paths to ours or theirs.

noemata fetch

noemata fetch does the reverse. It updates every file you haven’t changed since you last fetched or published to the latest revision, writes the files the revision added, and removes the files it deleted. A file you changed stays as it is. When the revision also changed that file, the file is a conflict. In a terminal, fetch asks about each conflict. Outside a terminal, fetch writes nothing unless you pass --accept-theirs to take the revision’s versions or --accept-ours to keep yours. A local server that drafts on disk makes the same updates each time a revision is published, and keeps your version of a conflicting file. Use fetch for a checkout with no server running.