The system is built on one decision repeated consistently: draw a hard boundary between what is identical on every machine and what changes with the OS or the operator. Get the boundary right and a single Core can serve every machine with zero special-casing.
Prefer to just read it? Browse the actual config for each layer → — real files, pulled straight from the source repos.
If it changes when the operating system changes, it does not belong in Core.
If it changes when you as an operator change, it does not belong in Core.
Everything left over is Core — and it lives in exactly one place.
git subtree — except Windows, which replicates Core nativelyzsh modules, tmux base, nvim, git/deltadotfiles-{MacBook,Windows,Fedora,Arch,…}package manager, clipboard shim, pathsdotfiles-Kali · dotfiles-Defenseoffensive engagement (Kali) · defensive detection/hunt (Defense)git subtree — each clone is self-contained (no submodule init).dotfiles-Kali stacks a Role layer on its OS layer; dotfiles-Windowscarries no core/ subtree and mirrors only the Neovim and starship configs. Edge colour tracks live vendoring drift — green = carrying Core v4.10.0, orange = behind (run a sync), cyan = replicated, with no vendored release to drift. Each vendoring repo's label shows the release it carries; the host's shows the Core ref its mirror came from.Each machine repo (except Windows, which replicates Core natively in PowerShell) vendors dotfiles-core under core/ as a git subtree. That physically copies Core in and commits it, so the repo clones and works with no submodule flags — important, since these are public showcase repos people will browse.
# one-time, inside an OS repo:
$ git subtree add --prefix=core https://github.com/dotgibson/dotfiles-core main --squash
# later, to pull Core updates down:
$ git subtree pull --prefix=core https://github.com/dotgibson/dotfiles-core main --squashMaintainers fan a Core change out to every OS repo in one shot withscripts/sync-core.sh, which prints the exact short SHA each repo receives so a sync is traceable.
Every dotfiles approach is a trade. This one optimizes for clone-and-go self-containment across many machines and a public, per-machine portfolio — paying a little vendored duplication for it. Here's how that lands against the usual alternatives, each of which wins in its own case.
A submodule stores a pointer, so a fresh clone is empty until git submodule update --init — the classic "I cloned it and nothing works" footgun. Subtree vendors the actual files, so every machine repo is self-contained and clone-and-go. The cost subtree pays back: a vendored copy in each repo (kept honest by the sync script + a manifest audit).
One repo + per-OS templates is the most DRY answer, and the right move the day you want to collapse the whole fleet into one. This system keeps the multi-repo portfolio instead — each machine is a clean, public, self-contained artifact. Because Core is already plain and OS-agnostic, moving to chezmoi later is a content migration, not a rewrite.
stow is a perfect, zero-magic symlink farmer over a single repo — and genuinely simpler if you have one machine. What it has no opinion about is layering or per-OS divergence, so a multi-OS setup drifts into host branches and .stow-local-ignore gymnastics. This system bakes the Core / OS / Role split in and ships its own idempotent symlinker (with backups + a dry-run).
The git --bare + alias trick is the leanest possible — no symlinks, files live in $HOME. Hard to beat solo. But it has no layer model, no per-OS story, noisy status against your whole home dir, and it is a real footgun on a shared or multi-user box. This trades that leanness for an explicit, auditable structure.
A system that can't name its own constraints isn't worth trusting. Don't use this if:
Load order is load-bearing. 00-tools initializes atuin (registering its widget), 10-options runs compinit (fzf-tab + carapace need it), and 35-fzf defines its widgets before 45-pluginsloads zsh-vi-mode, whose init fires the keybinding hook in 40-bindings. Every OS repo’s .zshrc just sources the vendored loader.zsh, which globs $ZSH_CFG/NN-*.zsh, sorts by the numeric prefix, and sources each — the order is the numbering, with no hand-maintained module list:
Two v4 refinements ride this loader. Profiles —CORE_PROFILE=minimal|standard|full — gate the Core band (00–69) by number: minimal stops after30-functions, standard after 50-op, andfull loads everything; the OS/role/host fragments (≥ 70) always load, so a lean profile can never drop essential setup. And theXDG split moves mutable state out of the symlinked config tree — history to $XDG_STATE_HOME, the compdump to $XDG_CACHE_HOME, plugins to $XDG_DATA_HOME — while each fragment’s byte-compiled.zwc stays beside it for fast startup.
Kali stacks three layers — Core, its apt OS layer, and an offensive role stage (dotfiles-Defense mirrors this on the blue side). Where a plain OS repo’s fragments end … 80-os 99-local, Kali drops in one more —85-offensive.zsh (role band 85), sorting between the two — for engagement scaffolding (scope-first workspaces, an audit-trail logshell, NetExec/BloodHound CE helpers). Engagement data never lives in the repo; it stays under~/engagements, and every tool is for authorized engagements with written rules of engagement only.
OS-native layers own more than packages and paths. On macOS,dotfiles-MacBook commits a full tiling-desktop setup — window manager, menu bar, and keyboard — themed to Core’s tokyonight palette so the GUI reads as an extension of the terminal, not a separate world.
i3-style tiling window manager — pure TOML, no SIP disable required, no daemon. alt drives focus, move, resize, and workspaces; its keymap is kept identical to GlazeWM (the Windows host WM) so the tiling workflow is the same on both OSes. JankyBorders rings the focused tile.
A programmable menu bar themed to tokyonight-storm, matching starship + tmux. Live AeroSpace workspaces on the left; CPU, memory, disk, network, and a click-to-toggle keep-awake on the right — every glyph from the one Nerd Font, no extra deps.
Caps→Ctrl/Esc, and a Tab-hyper layer that mirrors the WM verbs — hyper+hjkl to focus, hyper+1–5 for workspaces — so the whole tiling workflow stays on the home row.
The design decisions above are documented in full on this site. These are the long-form references worth reading next:
The per-distro lookup that turns the Fedora template into Arch, openSUSE, Alpine, and Gentoo — package manager, clipboard backend, and quirks, side by side.
Read it →dotfiles-KaliHow the Kali role layer maps to MITRE ATT&CK tactics — NetExec, BloodHound CE, Impacket, certipy-ad — and where loot lands under ~/engagements.
Read it →dotfiles-coreThe supply-chain stance: SHA-pinned plugins, pinned CI actions and pre-commit hooks, and how to report an issue.
Read it →dotfiles-WindowsThe structural audit behind the PowerShell host: fragment loader, coverage gate, and how the host layer bridges into WSL.
Read it →dotfiles-MacBookMoving an existing Mac onto the ecosystem without trampling what is already there.
Read it →dotfiles-ArchBare-metal groundwork for a minimal Arch box — user, sudo, git, and a UTF-8 locale — before bootstrap can run.
Read it →