Core concepts

Fabric keeps everything good about Git (changes, review, a single source of truth) while removing the foot-guns: force-pushes, rebase hell, merge conflicts, and lost work. The difference comes down to one idea: the canonical store is a single append-only operation log, not a chain of commits you can rewrite.

The append-only operation log

Every edit is one operation: an entry appended to a single log. The log only ever grows in one direction: forward, at the end. That end is called the frontier, and it’s the only place you can write.

Two things follow, and they’re the whole model:

• You can only work at the end. Every change forks from the current frontier and appends new operations onto it. You never edit, reorder, or delete an operation that’s already in the log. If you’d normally rebase or amend, you just append more operations instead, so there is no rebase, no --force, and no history rewrite.
• The full history stays, and stays readable. Because nothing is ever overwritten, the entire past is still there. You can replay the log up to any earlier point and see exactly how the repo looked then. But that’s read-only: you can view any point in the past, and you can only write at the frontier. (See Time-travel.)

A useful picture: a ledger you can only ever add the next line to. Every line above stays, exactly as written, and you read it freely, but you only ever write at the bottom, and you can’t go back and edit a page.

Because nothing is rewritten, nothing gets lost: there are no detached commits to drop and no force-push to overwrite a teammate’s work.

How merging works

Merging still happens: combining concurrent work is the core job of any version-control system. What changes is how: Fabric merges at the operation level, automatically and continuously, instead of stopping to make you resolve a conflict by hand.

When two people (or an agent) edit the same file at the same time, their edits are operations that converge automatically into a single consistent state. The key shift is where a conflict lives:

• Conflicts never land in your code. You never see <<<<<<<, =======, or >>>>>>> written into a file, and editing never halts with a “merge failed: fix it by hand” error. Your working files always have one well-defined state.
• A real overlap still has to be reconciled, away from your files. When two edits touch the same lines, that overlap doesn’t vanish; it stays attached to the change. Until it’s reconciled the change simply isn’t ready to accept, and the review page shows a neutral “still reconciling” state rather than splicing markers into your working files. The reconciliation happens on the change, not in your source.
• Review owns semantics. Automatic convergence guarantees a consistent file, not a correct one. Two people editing the same function can both land cleanly yet still produce combined logic that needs a human’s eye. That judgment lives in propose → review → accept.

Merging and overlaps still exist in Fabric. It keeps the reconciliation out of your code, and it moves the part that actually needs human judgment (“is the combined result correct?”) into review.

Review and approval

A change can’t reach the trunk on its own. After you propose it, it goes through review, and it must be approved before it can be accepted. Approval is a deliberate sign-off by a reviewer, not something the change does automatically and, as a rule, not something you do to your own change. More than one approval is welcome. This is what keeps unreviewed or half-finished work from ever landing on a trunk others build on.

The merge queue

Accepting a change does not always land it on trunk immediately. When a trunk is configured to batch accepts (see queue settings), an accepted change joins a merge queue: a second frontier, distinct from trunk. The change merges into a staged candidate frontier (trunk plus the queued changes), its checks run against that staged state, and trunk advances to it only once a check passes. Several changes can be trialled at once, stacked in order, and the longest passing prefix lands together in one step. A change that fails is evicted, and the changes behind it re-form the batch without it and are re-tested.

The guarantee is the same one gated accept gives: trunk only ever lands on a state a required check passed against. The queue just lets many changes move toward trunk in parallel instead of one at a time, without a throwaway merge branch: a candidate is a computed frontier (an op-set union plus a replay), not a stored ref.

You can watch the queue in the web Merge queue view or with fabric queue: the ordered positions of the changes waiting to land, the staged candidate frontier, each candidate’s check status, and the terminal outcome (promoted or rejected). Both update live as the queue works. A repo on the default serial path (batch size one) never queues: each accept lands inline once its checks pass.

Comments

Review comments are operations too. A comment is an entry in the same log as every edit, appended at the frontier its author was reading, so it versions with the file it annotates. A comment belongs to the versions at or after the point it was written: the version you view decides which comments you see, by the same reachability rule that decides which edits are present.

A comment never changes the file. Replaying the log builds the file as plain text, and the comments are drawn as an overlay on top, each pinned to the span it was left on. Nothing is spliced into the source; the comment layer sits beside the text and follows it as the text edits underneath.

Mapping from Git

Change

A change is Fabric’s unit of work: it replaces the branch. You fork an isolated op-set from the current trunk frontier, edit, and integrate it forward through propose → accept. Isolation is a guarantee, not ceremony: unreviewed ops can never land on trunk, because propose → review → accept is the only path in. A half-finished or unapproved change cannot corrupt what others build on.

Trunk

The trunk is the converging head your changes integrate into: Fabric’s main. Trunks are per-subtree: independent areas of the repo advance independently rather than false-coupling through one global head.

fabric accept never edits trunk directly. The hub merges your change onto the current trunk, runs the required checks against that exact merged result, and advances trunk only if they pass. If another change lands first, the hub re-merges on the new tip and re-checks before advancing, so trunk only ever moves to a state a check has passed against. Two changes that touch disjoint subtrees accept in parallel; only overlapping ones take turns.

Frontier

The frontier is the end of the log: the latest point, and the only place you can write. It’s Fabric’s analog of a ref or HEAD: it identifies a version of the repo, and replaying the log up to it produces the file state at that point. New work always attaches here.

Forward-only: what does not exist

• No rebase, no --force, no history rewrite. The log only ever grows.
• No detached work you can lose. Your work lives on the change until accepted.
• No merge-marker editing on push. Trunk only changes when a change is accepted.

You cannot go back to an earlier point in the log and fork new work from it. The only direction is forward, at the frontier. Viewing the past is still easy, but strictly read-only: see Time-travel.