IF Commons GitHub

AnyFS Git: the store of a branch

0003Active

0003-git-ref · owner if · domain commons

Requirements

FR-001checkpassing

The revision of a file MUST be sha256: and the digest of its bytes, the same as in every other store, and the library MUST give Git's names for the blob and the newest commit and the mode of the file beside it; a digest kept for the name of a blob MUST never be forgotten, since the name stands for the bytes.

Enforced (check): .github: cd commons/anyfs-git && bun run verify — suite/ref.test.ts

Proved by: anyfs-git/suite/ref.test.ts

Written in: anyfs-git/src/physical/objects.ts, anyfs-git/src/physical/ref/mod.ts

Tests: passed: suite/ref.test.ts the revision of a file is sha256 and the digest of its bytes, and Git's names for the blob

FR-002checkpassing

A store of a branch MUST never change the working tree, the index or the head of the repository: a commit MUST be made in a temporary index and a temporary folder and the branch moved by update-ref, and a store of a branch that is checked out in a working tree (this one or another) MUST be refused unless the caller allows it.

Enforced (check): .github: cd commons/anyfs-git && bun run verify — suite/ref.test.ts

Proved by: anyfs-git/suite/ref.test.ts

Written in: anyfs-git/src/physical/ref/branch.ts, anyfs-git/src/physical/ref/mod.ts

Tests: passed: suite/ref.test.ts a store of a branch never changes the working tree, the index or the head, and a branch th

FR-003checkpassing

A write, a delete and a rename MUST check what they expect (no object, the object at a revision, or anything) against the file at the tip they read, and a branch that moved while the change was made MUST be read again and the change checked again, so that two writers of different files both succeed, two writers who expect the same revision of a file cannot both succeed, and the commit of another writer is never overwritten; a branch that keeps moving MUST end as a retryable unavailable after the tries.

Enforced (check): .github: cd commons/anyfs-git && bun run verify — suite/ref.test.ts

Proved by: anyfs-git/suite/ref.test.ts

Written in: anyfs-git/src/physical/ref/branch.ts, anyfs-git/src/physical/ref/mod.ts

Tests: passed: suite/ref.test.ts writers are decided by what they expect: two who expect the same revision cannot both win,

FR-004checkpassing

A batch MUST be one commit with every change in it, all or none, each change checked against the state the changes before it made; a change that changes nothing (the same bytes, a delete of what is not there) MUST make no commit.

Enforced (check): .github: cd commons/anyfs-git && bun run verify — suite/ref.test.ts

Proved by: anyfs-git/suite/ref.test.ts

Written in: anyfs-git/src/physical/ref/branch.ts, anyfs-git/src/physical/ref/mod.ts

Tests: passed: suite/ref.test.ts a batch is one commit with every change, each checked against the changes before it, all o

FR-005checkpassing

A history MUST be the commits of the first-parent line that changed the file, newest first, each with its revision, size and instant, and the library MUST give each commit's identity and message besides; a file that is not at the tip MUST have no history.

Enforced (check): .github: cd commons/anyfs-git && bun run verify — suite/ref.test.ts

Proved by: anyfs-git/suite/ref.test.ts

Written in: anyfs-git/src/physical/ref/mod.ts

Tests: passed: suite/ref.test.ts a history is the commits that changed the file, newest first, with who made them, and a fi

FR-006checkpassing

A branch with no commit MUST read as empty and be made by the first write with no parent, in a repository that is bare or not.

Enforced (check): .github: cd commons/anyfs-git && bun run verify — suite/ref.test.ts

Proved by: anyfs-git/suite/ref.test.ts

Written in: anyfs-git/src/physical/ref/branch.ts, anyfs-git/src/physical/ref/mod.ts

Tests: passed: suite/ref.test.ts a branch with no commit reads as empty and is made by the first write with no parent, in a

FR-007checkpassing

The store MUST hold regular files: a symbolic link or another repository named by a path MUST be refused as outside its scope and left out of a list, a path where Git would hold a file and a folder of the same name MUST be refused, and a path that another file system could not hold MUST be refused (unless the caller turns that off).

Enforced (check): .github: cd commons/anyfs-git && bun run verify — suite/ref.test.ts

Proved by: anyfs-git/suite/ref.test.ts

Written in: anyfs-git/src/physical/ref/branch.ts, anyfs-git/src/physical/ref/mod.ts

Tests: passed: suite/ref.test.ts links and other repositories are refused and left out of a list, a file and a folder of on

FR-008checkpassing

A list MUST give the files below a prefix in the order of their paths, in pages with a cursor, with the revision of each, and a name that is not text in its normal form MUST not be listed; a rename MUST be one commit and MUST refuse a destination that is there.

Enforced (check): .github: cd commons/anyfs-git && bun run verify — suite/ref.test.ts

Proved by: anyfs-git/suite/ref.test.ts

Written in: anyfs-git/src/physical/objects.ts, anyfs-git/src/physical/ref/mod.ts

Tests: passed: suite/ref.test.ts a list gives the files below a prefix in order, in pages with a cursor, with their revisio

Acceptance scenarios

  1. Given a repository with a working tree, When a store writes to a branch that is not checked out, Then git status, the index and the head are as they were, per FR-002.
  2. Given two writers who expect the same revision of one file, When both write at once, Then exactly one succeeds and the other has a conflict, per FR-003.
  3. Given a batch of three changes, When it is made, Then the branch has one new commit that holds all three, per FR-004.
  4. Given a file written three times, When its history is read, Then it is three revisions newest first, per FR-005.
  5. Given a branch that does not exist in a bare repository, When a file is written, Then the branch is made with a commit that has no parent, per FR-006.
  6. Given a tree with a symbolic link, When it is read by its path, Then it is refused, and a list does not hold it, per FR-007.
  7. Given twenty-five files, When they are listed ten at a time, Then three pages give them in order, per FR-008.

Out of scope

Edge cases

  • A repository whose tip moves while a change is made is read again and the change checked again (FR-003).

Assumptions

Open questions

  • None.

Key entities

  • Branch, Working tree, Revision, Identity.

Success criteria

SC-001success criterion

Every behaviour is tested in real repositories in temporary folders, with no network and no real time.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Titles, headings, exports, tables, columns and requirements. Esc closes.