Skip to content

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.

fm sync [--frozen] [--locked] [--offline]
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

Example

$ fm sync --frozen