Git designed for AI agents.
docs: the watermark fsync before git's lock, and bucket directories never removed while served
Federico Elia2dda256714e5
diff --git a/doc/graft/PLAN7.md b/doc/graft/PLAN7.mdindex e8a6292..62d9dcb 100644--- a/doc/graft/PLAN7.md+++ b/doc/graft/PLAN7.md@@ -714,10 +714,12 @@ repository-wide lock.* It fsyncs the tables not yet fsynced, `tables.list` and the directory.* When the repository has been idle for a second, or the process stops,and nothing is live, the step clears the marker:+ * It fsyncs the watermark and its directory (see *Watermark* below),+ before git's lock, so that this fsync does not hold the transactions.* It takes git's lock without waiting. The lock is created by linking atemporary file that holds a tag and a random nonce.- * It fsyncs what was written since, then the watermark and its directory,- marks the state clean, and releases the lock. The release removes the lock only if it is still the same+ * It fsyncs what was written since, marks the state clean, and releases+ the lock. The release removes the lock only if it is still the samefile with the same nonce: an inode is reused as soon as it is freed, soa lock that someone else replaced is never removed.* Last, it removes the marker, under a per-repository file lock that@@ -728,15 +730,19 @@ repository-wide lock.servers stopped, so a clean reboot does not rehydrate them.* *Watermark.* While a repository of the owner is dirty and has a reftablestack, the syncer writes its watermark (`graft/storage/applied`) atomically- without fsync (`CanDefer`).+ without fsync (`DefersWatermark`).* After a kernel restart a dirty cache is moved aside whatever its watermarkholds, and after a process restart the page cache kept the write. Anadvance only changes the sequence; the repository ID was written withfsync by the hydration, so a lost or torn advance leaves the recovery'sdecision as it was.- * The step that clears the marker under git's lock, and `Forget` of a- repository kept in place, fsync the watermark and its directory first. A+ * Every removal of a dirty marker fsyncs the watermark and its directory+ first, if there is one: the step that clears it (before it takes git's+ lock), the step of a repository whose stack is gone, and `Forget`. Afailed fsync makes the repository untrusted, as for the stack.+ * The watermark cannot change between that fsync and the removal: the+ syncer writes it only under its repository lock, which the step and+ `Forget` hold.* Hydration, import and the gate write it with fsync, as does a writewhose directory is missing.* *Write failure.* Only a failed fsync means the kernel may have droppeddiff --git a/doc/graft/STORAGE.md b/doc/graft/STORAGE.mdindex 54504e7..7b10dbd 100644--- a/doc/graft/STORAGE.md+++ b/doc/graft/STORAGE.md@@ -50,7 +50,10 @@ maintenance). Where they differ, PLAN7.md is the later decision.link(2), because gocloud's file driver does not make its own create-only writeatomic (it checks that the key is absent, then renames onto it, so two writersof one key would both succeed). A file bucket therefore needs a filesystem- with hard links. A changeset never references a pack that is not completely+ with hard links. Never remove or replace a directory of a file bucket while a+ server uses the bucket: a node remembers which directories it has made+ durable, by inode, and a directory created again could reuse an inode it+ remembers. A changeset never references a pack that is not completelyuploaded. Changesets written by v0.1.0 keep their keys(`repos/<repo_id>/packs/<sha256>.pack`, shared by identical packs), whichstay readable; the database refuses such a key in a new changeset, so every