The macOS OS-native layer — Homebrew, AeroSpace tiling, and desktop tooling over the shared Core.
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
dotfiles-MacBook is the OS-native layer for macOS (Apple Silicon / Intel) —
one node in a cross-platform dotfiles system. The shared Core (zsh, tmux,
Neovim, git, starship, mise) is authored once in
dotfiles-core and vendored under
core/ via git subtree, so a clone is self-contained. This repo adds only what
is specific to macOS: the Brewfile (brew bundle), Ghostty, the 1Password SSH
agent, the native pbcopy clipboard — plus a committed tiling-desktop layer:
AeroSpace, SketchyBar, and Karabiner, themed to match Core.
macOS is its own lineage — built directly on Homebrew, not stamped from the Fedora template. The full docs live on the documentation site.
The system is three layers, each building on the one below:
| Layer | Lives in | Owns |
|---|---|---|
| Core | dotfiles-core → vendored into every OS repo's core/ |
zsh, tmux, nvim, git, starship — identical everywhere |
| OS-native | dotfiles-{MacBook,Windows,Fedora,Arch,openSUSE,Alpine,Gentoo} (this repo among them) |
package manager, clipboard, paths |
| Role | dotfiles-Kali, dotfiles-Defense |
offensive / defensive tooling |
The Brewfile is a Ruby DSL (brew bundle); everything else is shell + config over Core.
A Mac and the Xcode Command Line Tools
(xcode-select --install) — that brings Git. bootstrap.sh provisions the rest
via Homebrew. Already have a Mac configured a different way? See the
migration guide to move onto this layout safely.
git clone https://github.com/dotgibson/dotfiles-MacBook ~/dotfiles-MacBook
cd ~/dotfiles-MacBook
./bootstrap.sh --links-only --dry-run # preview the symlink plan (changes nothing)
./bootstrap.sh # Homebrew + brew bundle + symlinks
exec zsh
./bootstrap.sh --macos-defaults # optional: apply system prefscore/ is a vendored subtree and is already present in a clone — there is no
submodule step. Flags: --dry-run/-n, --links-only, --no-brew,
--set-shell (make the Homebrew zsh your login shell), --macos-defaults.
Only what changes with the OS. The heavy lifting — the shell modules, editor, and prompt — comes from vendored Core; this repo owns the macOS specifics:
Brewfile— Homebrew packages (CLI + casks + fonts), the source of truthos/macos.zsh,os/macos.gitconfig,os/macos.conf— the macOS overlaysmacos/defaults.sh— thedefaults writesystem-preferences script (opt-in)aerospace/,sketchybar/,karabiner/,ghostty/— the desktop toolingcore/— vendored fromdotfiles-core(read-only here; edit upstream)
The things worth knowing — Homebrew on /opt/homebrew vs /usr/local, the native
pbcopy/pbpaste clipboard, the 1Password SSH agent, and the macOS keychain —
are written up on the hub, alongside the migration guide for
moving an existing Mac onto this layout:
This is an OS-native layer, so the contribution rule is a boundary rule:
- Never hand-edit
core/. It is a vendored copy ofdotfiles-coreand is overwritten on the next sync. Fix shared config upstream indotfiles-core, runmake auditthere, thenmake syncfans it out here. - Keep changes genuinely macOS. If it would be identical on every machine, it belongs in Core; if it changes with the operator, it belongs in a role repo.
- Green the gate. CI runs shellcheck + shfmt +
bash -n/zsh -n+make test-repo(as individual targets);make lintbundles the same checks locally, andpre-commit installmirrors them at commit time.
Bugs and ideas: open an issue.
Distributed under the MIT License. See LICENSE for more information.
Garrett Allen - @gerrrrt - [email protected] - LinkedIn
Project Link: dotgibson