Rebase notes

[dholms]

A rebase is a commit that alters the history of the repo

A rebase can have anything in it: a total rewrite of the repo history, a total rewrite of the repo contents, etc.

A “happy path” rebase is a rebase that leaves the data root untouched & simply signs a new top-level commit with prev: null

Currently the PDS only produces happy-path rebases.

Event stream semantics

A rebase event has message type #commit (just as a normal commit does).

It has a boolean flag rebase set to true.

prev is set on the event (but not on the new commit block). This prev is the previous commit of the repo before the rebase & is just meant to be used for bookkeeping on the consumer side

Similarly to commits, blocks will contain any new blocks created for the rebase. In the case of happy path rebases, this is only the new commit block.

When a rebase is added to an outgoing stream, it will invalidate all previous commits on the stream. Anyone that asks for backfill will not get commits that were previously in the stream.

Processing recommendations

When a repo is rebased, you should perform garbage collection on your store of that repo

• clean up any unreferenced blocks
• update all existing referenced blocks to be “part of” the rebased commit

In the case of a happy path rebase, you should not need to go to the provider for any additional information - you’ll already have the one block you need.

For a “dirty” rebase, you can opt to do one of the following:

• clear the repo & download the repo fresh (with com.atproto.sync.getRepo)
• walk the structure, filling in blocks as you go with com.atproto.sync.getBlocks

Generally I would recommend the first, unless you have reason to believe the repo is very large & you’re only missing a few blocks.

[bnewbold]

With recent changes to how repo history works, going to close this as outdated (though def still interesting as a historical note)