IF Commons GitHub

A branch of Git as a store of files

0013Active

0013-grc-gitref · owner if · domain grc

Requirements

FR-001checkpassing

commit MUST write the files whose bytes differ from the tip of the branch in one commit by the identity of the store (creating the branch, with no parent, where it does not exist), MUST make no commit where no file differs and say so, and MUST give the commit and the paths that differed.

Enforced (check): .github: cd commons/grc && bun run verify — suite/gitref.test.ts

Proved by: grc/suite/gitref.test.ts

Written in: grc/src/stores/gitref/mod.ts

Tests: passed: suite/gitref.test.ts a commit writes only the files that differ, makes none where none does, and creates the br

FR-002checkpassing

A commit MUST NOT touch the working tree, the index or the checked-out branch of the repository, MUST be made at the instant given where one is (its author and committer date), and MUST NOT be signed, so that a program with no key can write it.

Enforced (check): .github: cd commons/grc && bun run verify — suite/gitref.test.ts

Proved by: grc/suite/gitref.test.ts

Written in: grc/src/stores/gitref/mod.ts

Tests: passed: suite/gitref.test.ts a commit leaves the working tree, the index and the checked-out branch as they were, is ma

FR-003checkpassing

A path MUST be a relative path of letters, digits and . _ @ + = , - in segments that do not start with a hyphen, with no ..; any other MUST be refused, and nothing written.

Enforced (check): .github: cd commons/grc && bun run verify — suite/gitref.test.ts

Proved by: grc/suite/gitref.test.ts

Written in: grc/src/stores/gitref/mod.ts

Tests: passed: suite/gitref.test.ts a path that is not a relative path of the branch is refused and nothing is written

FR-004checkpassing

The branch MUST be written with the tip it was made on as the guard: where it moved while the commit was made, the commit MUST be refused as moved and the branch left as the other writer made it.

Enforced (check): .github: cd commons/grc && bun run verify — suite/gitref.test.ts

Proved by: grc/suite/gitref.test.ts

Written in: grc/src/stores/gitref/mod.ts

Tests: passed: suite/gitref.test.ts a branch that moved while a commit was made is refused as moved and left as the other writ

FR-005checkpassing

read, list, history and head MUST read from the branch: read the bytes of a file at the tip or at a commit (nothing where there is none), list the files under a folder in order, history the commits that touched a path newest first with their instant and subject, and at the newest commit made at or before an instant (the second itself included), nothing where there is none or the instant is not one.

Enforced (check): .github: cd commons/grc && bun run verify — suite/gitref.test.ts

Proved by: grc/suite/gitref.test.ts

Written in: grc/src/stores/gitref/mod.ts

Tests: passed: suite/gitref.test.ts files are read, listed and followed through the history from the branch, and the state at

FR-006checkpassing

push MUST push the branch to a remote and nothing else, MUST NOT force, and a remote that has moved MUST be an error that says so, the branch left as it was.

Enforced (check): .github: cd commons/grc && bun run verify — suite/gitref.test.ts

Proved by: grc/suite/gitref.test.ts

Written in: grc/src/stores/gitref/mod.ts

Tests: passed: suite/gitref.test.ts the branch and only it is pushed, and a remote that has moved is refused and not forced

Acceptance scenarios

  1. Given a repository with a branch checked out and uncommitted work, When a file is committed to the evidence branch, Then the checked-out branch, the index and the work are as they were, per FR-002.
  2. Given a file committed, When the same bytes are committed again, Then no commit is made, per FR-001.
  3. Given three commits at three instants, When the state at an instant between two is asked, Then it is the earlier commit, per FR-005.
  4. Given a remote that has moved, When the branch is pushed, Then it is refused and not forced, per FR-006.

Out of scope

  • Which files are kept, and their meaning: the program that writes them.
  • Signing the commits: a seal of the journal's head is a person's, made elsewhere.

Edge cases

  • A repository with no commit at all can still have the branch, per FR-001.

Assumptions

  • Git is installed; its plumbing is the same on every system.

Open questions

  • None.

Key entities

  • Branch store - a branch of a repository that holds files written by a program and read by anyone.

Success criteria

SC-001success criterion

A program that writes once a minute makes a commit only when something changed, and no person's checkout is disturbed.

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

Cited by

GRC, stores/gitref/mod

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