sync¶
Bring the checkout current, materialise content, match the lock.
The one-stop: fast-forward or rebase the current branch (asking
before anything conflicted or shared; a branch started on another
with fm start --from follows its parent; a directory with no git
history, no repository or no commit, has nothing to follow), remove
what a removed package left under packages/, fetch origin's
state store into the checkout's mirror for the gate to read, then
every extension's fragments, skills, and hooks, then the two locks.
Both halves match their lock the way uv does: toolroom.sync for the
tools, uv sync for the environment, each writing its lock when
there is none or the declarations have moved past it. Last, the
composed and generated files are written again, since both read the
locks. Idempotent: re-running it is the recovery procedure.
The three options are uv's and reach both halves: --frozen
installs each lock as it is and resolves nothing, --locked
refuses when a lock is not current, and --offline uses what the
machine already holds. As uv's two leave its lock unchanged, ours
change nothing a commit holds: the branch is not moved and no
tracked file is written, while the checkout's own untracked files
are. They differ as uv's do, in whether the locks are judged:
--locked refuses a stale one, so CI's setup runs it and a job
holds what a person's checkout holds; --frozen takes them as
they are, which is how the per-command hook brings a checkout
current before every command, running this verb's work frozen and
offline (livery.workshop._reconcile.apply). Judging the tracked
files stays the drift check's.
A frozen sync reads the receipts first (livery.workshop._reconcile.current). When the environment, the tools and the delivered files all match them, its local steps have nothing to do and are skipped, and nothing is printed, so the hook costs a current checkout those reads and nothing else. A plain sync renders and installs again regardless, since a fragment edit is in no receipt; the tools' supply alone reads its receipts in every mode (livery.workshop._tool_tasks.sync_tools).
A checkout the first act moved holds code this process has not
loaded, so the rest of the sync is handed to a fresh process on
that code; the handoff is named, and a process that cannot be
started continues on the loaded code and says so. An extension the
workspace lists that the command started without is mounted the
same way before anything renders or locks: a sync never renders
without one. A newly listed extension is installed first, the way
the workspace resolves it: the sync writes the project file alone,
whose dev group then names the extension's distribution, and runs
uv sync, which locks and installs through the file's
[tool.uv.sources] and indexes. So an extension the workspace
sources from a path or from git installs from there. When no
installed distribution declares the extension even then, the sync
refuses, naming the extension and the list that brings it. Before
that refusal, and when the install fails, it puts the project file,
its receipt and uv.lock back as they were. A uv sync that
moves or removes the distribution of the workshop, or of an
extension the command mounted, hands the rest of the sync over the
same way, before anything reads it again: this process found it
where the install no longer puts it. A handoff that cannot start
then refuses, and the next sync completes.
Shell completion answers from a manifest this command wrote as it
started, from what was installed then. A sync that changed the
distributions the environment installs, run by a person at a
terminal, starts the detached rebuild of that manifest for the
directory the command was typed in
(livery.footman.refresh_completion), so the next Tab there
offers the tasks an installed extension brings. A sync that changed
nothing installed starts nothing, and so does one no person is
there for, in CI or under --no-input. A rebuild that cannot
start leaves the sync's outcome as it is.
| Parameter | Type | Default | Description |
|---|---|---|---|
--frozen |
flag | false |
|
--locked |
flag | false |
|
--offline |
flag | false |
Returns: Whether the local steps ran. A frozen sync of a current checkout returns False. — true/false