Consuming Core in an OS Repo

Consuming Core in an OS Repo

This page covers the mechanics of pulling Core into a machine repo and keeping it up to date. For the why (subtree vs. submodule, the layer model), see Architecture & the Three-Layer Model.

One-time: vendor Core into core/

Inside the OS repo (for example dotfiles-Fedora), add Core as a squashed subtree under core/:

git subtree add --prefix=core https://github.com/<you>/dotfiles-core main --squash

This physically copies Core's files into core/ and commits them. The repo now clones and works with no submodule flags — clone-and-go, which matters for public showcase repos.

What bootstrap symlinks

The OS repo's bootstrap.sh symlinks the vendored Core files into place alongside its own OS-native files:

• core/zsh/*.zsh → sourced by the OS repo's .zshrc loader
• core/tmux/ → ~/.config/tmux/
• core/nvim/ → ~/.config/nvim/
• core/git/ → git config (layered via [include])
• core/starship/starship.toml → ~/.config/starship.toml
• core/mise/config.toml → mise global config
• core/bin/ → clip / clip-paste into ~/.local/bin

Note: core/scripts/ (the dev tooling) is not symlinked — those run in the Core repo only.

The .zshrc loader contract

The OS repo's .zshrc sources the Core modules in the canonical order, then its own native and local layers:

tools → ui → options → history → aliases → git → functions → fzf →
bindings → plugins → op → maint → update → os → local

os is the OS repo's native layer (package manager, clipboard, paths); local is your untracked machine-specific overrides. (dotfiles-Kali inserts an offensive stage: … os offensive local.) See The Zsh Module System for why the order is load-bearing.

Updating Core everywhere: sync-core.sh

After you change Core here and push, fan the update into every OS repo's core/ subtree with the maintain button:

./scripts/sync-core.sh                       # pull into every repo found
./scripts/sync-core.sh --dry-run             # show what would happen, touch nothing
./scripts/sync-core.sh dotfiles-Fedora       # only specific repos

It assumes all OS repos are cloned as siblings under one parent dir (override with REPOS_ROOT).

The fan-out gate

sync-core.sh is the single point where Core is vendored into all nine repos, so a defect here amplifies N-way. It therefore protects the fan-out:

• it runs the audit first and refuses to fan out a red tree (SYNC_SKIP_AUDIT=1 is the documented escape hatch; --dry-run is exempt),
• it warns when local HEAD differs from the remote tip that actually fans out (subtree pull fetches the remote tip, not your working tree), and
• it skips any OS repo with a dirty tree (subtree merges into a clean state only).

It prints both the SemVer (core.version) and the commit SHA that landed, so a sync is traceable. Push each updated OS repo when you're satisfied.

Useful env overrides

Variable	Purpose
REPOS_ROOT	parent dir holding the OS repos (default: parent of Core)
CORE_REMOTE	remote name/URL the OS repos pull Core from
CORE_BRANCH	the Core branch to vendor (default main)
SYNC_SKIP_AUDIT	1 to skip the pre-fan-out audit (escape hatch)

Checking which Core a machine carries

From inside any OS repo, core-version reports the vendored Core's SemVer (read from core.version), and core-doctor reports which tools that box detected. The subtree squash commit records the exact Core commit that landed.

See also

• Architecture & the Three-Layer Model
• Porting to a New Distro — stamping a brand-new OS repo.
• The Audit (Quality Gate) — what "audit-green" means.