Artifact a9b426dba9ff64169b24f53881becf27849bebae39d8adcaf05c2ccc0ca04416:
- File
docs/site/content/docs/concepts/repository-state.md
— part of check-in
[93ad669695]
at
2026-10-23 20:53:50
on branch main
— docs: reorganise into get-started, concepts, guides, reference
Move the flat docs pages into sections, keep each old URL as an alias, split sparse cones from horizons, and add concept pages for artifacts, repository state, sync, sub-manifests and signing plus a settings reference. Audit the moved pages against the code and fix drift. (user: [email protected], size: 4333) [annotate] [blame] [check-ins using] [more...]
--- title: Repository state weight: 30 --- [Artifacts](/docs/concepts/artifacts/) are the only facts a repository records. Everything else, such as which check-in is the tip of trunk, which branch a check-in is on, or which leaves are open, follows from them. `draft-fossil-repo-state-00` specifies that derivation, so two implementations reading the same artifacts reach the same answers. The one exception is the current trunk, which also reads the repository's `main-branch` setting (§9). ## The tables A `.fossil` file stores the artifacts in `blob` and `delta`, and keeps the derived state in tables beside them, so a query does not re-parse every artifact. | Table | Holds | |---|---| | `blob` | Every artifact, compressed, by `rid` and name (`uuid`). A row with no content is a phantom. | | `delta` | Which blobs are stored as deltas, and against what. | | `phantom` | Names the repository knows of but does not hold yet. | | `event` | One row per check-in, tag, wiki edit, ticket change and so on: the timeline. | | `plink` | Parent links between check-ins, with which parent is primary (§3). | | `mlink` | Which file changed in which check-in, and from which earlier version. | | `filename` | The file names `mlink` refers to. | | `tag`, `tagxref` | Tag names, and each tag's effect on each check-in: cancel, singleton or propagating (§5). | | `leaf` | Check-ins with no child on their own branch (§7). | | `orphan` | Delta manifests whose baseline is absent. | `blob` and `delta` are the source. The others are derived. ## Crosslinking **Crosslinking** reads one artifact and writes its effects into the derived tables (§4). A check-in adds its `plink` and `mlink` rows and its `event` row. Its `T` cards, or a control artifact's, set `tagxref` rows and propagate along primary children until a cancel or another value blocks them (§5.4). Leaves are rechecked as parents gain children and as tags move (§7.6). Artifacts can arrive in any order. Sync, clone, a commit and a rebuild all crosslink, and an artifact whose parent has not arrived yet is linked again when it does. Branches are not stored as such. A check-in's branch is the value of its `branch` tag, inherited from its primary parent unless a tag on it says otherwise (§6). Name resolution (§8) turns a branch name, tag or `trunk` into one check-in: `Repo.ResolveVersion(name)`. `Repo.CurrentTrunk()` returns the tip of the main branch (§9). ## Rebuild gives the same rows Because the derived tables are a function of the artifacts, they can be thrown away and computed again. go-libfossil's rebuild (`verify.Rebuild`, internal) empties the crosslinked tables and runs the same crosslink sweep a clone runs, so derived state has one owner. The tables it refills are `event`, `plink`, `leaf`, `mlink`, `tagxref`, `forumpost`, `attachment`, `backlink`, `cherrypick` and `orphan`, plus the sync bookkeeping tables `unclustered` and `unsent`. The conformance suite checks this against fossil itself: - Each scripted case in `conformance/repostate_*_test.go` loads a sequence of artifacts into go-libfossil (one sweep, one artifact at a time, and through rebuild) and into fossil(1). The rows must equal the expectation written from the draft, and fossil's rows must equal it too: its per-artifact crosslink for a crosslink case, `fossil rebuild` on a copy for a rebuild case. The compared tables are `plink`, `tagxref`, `event`, `phantom`, `leaf`, `orphan` and `mlink`. - `TestRepoStateCorpus` takes real repositories (named in `CONFORMANCE_REPOS`) and derives their tables three ways: `fossil rebuild` on one copy, as the reference; go-libfossil's rebuild on a second; a crosslink sweep over emptied tables on a third. It compares `event`, `leaf`, `mlink`, `phantom`, `plink` and `tagxref` column by column. It runs only when fossil(1) is present. Where fossil departs from the draft text, the case records it and names the draft change proposed. The requirements are listed in `conformance/requirements/repostate.tsv`. ## Where the code is - `internal/manifest`: crosslinking (`crosslink.go`), re-derivation (`rederive.go`), the timeline. - `internal/tag`: tag application and propagation. - `internal/leaf`: the leaf table. - `internal/verify`: integrity checks and rebuild. - `internal/repo`: the schema and the `main-branch` setting.