dotgibson

About The Project

dotfiles-core is the foundation layer — the shell, editor, and tooling config that stays identical on every machine. It's authored once here and vendored into each per-OS repo, so you don't install this repo directly: you clone the repo for your platform (macOS, Kali, Fedora, …), which already carries Core inside it. Full docs live at the documentation site.

One tree is the exception to "authored once here": the editor lives in dotfiles-nvim, and Core vendors it in at a pinned release — so Core is a consumer too, not only a source.

The system is three layers — Core here, an OS-native layer per machine, and an optional role layer — each building on the one below. ARCHITECTURE.md is the canonical statement of the model and the boundary test that places a file in one:

Layer	Lives in	Owns
Core	this repo → vendored into every OS repo's core/	zsh, tmux, git, starship — identical everywhere; plus nvim, vendored from dotfiles-nvim
OS-native	dotfiles-{MacBook,Windows,Fedora,Arch,…}	package manager, clipboard, paths
Role	dotfiles-Offense, dotfiles-Defense	offensive / defensive tooling

The rationale (why vendoring, how a sync fans out) lives on the docs site; this README is the quick tour.

Like most dotfiles, this started as a personal itch. Every tweak to my terminal led to refactoring something else, and the cycle didn't stop until the whole environment finally felt like home. Once it did, I wanted the exact same setup on every machine I touch — no productivity gaps when hopping between them. That's dotgibson: my terminal workflow, made portable.

It won't be everyone's ideal — dotfiles are personal — but the pieces here are meant to be borrowed, and it keeps evolving as I find better ways to build it. Suggestions and issues are always welcome; thanks to everyone whose own configs inspired this one.

Languages

Tools

Getting Started

Every repo follows the same shape: clone, optionally dry-run to preview the symlink plan, then bootstrap. Core is vendored, so a clone is self-contained with no submodule flags. Just pick a platform and go.

Prerequisites

Your platform's base toolchain, plus curl on the Debian and Fedora families — bootstrap.sh fetches the pinned upstream assets the package manager cannot supply, so it checks for what it needs up front and stops with the full list if anything is missing. Most desktop and server installs already have curl; a minimal or container image often does not (sudo apt-get install -y curl / sudo dnf install -y curl). bootstrap.sh provisions everything else (zsh, tmux, nvim, starship, and friends).

Git is not a hard requirement. It is needed only for the one-time tpm clone, and its absence is a warning rather than a stop — the reverse of what this section claimed until the first genuinely unstubbed bootstrap run proved otherwise (#742).

Platform-specific setup notes live in each OS repo's README and the docs site; the essentials:

• macOS — Xcode Command Line Tools
• Windows — PowerShell 7 and Developer Mode
• Kali — built for WSL2

Installation

1. Clone the repo for your platform. Releases are tagged per repo — replace vX.Y.Z with the latest tag from that repo's Releases page.

   # MacOS
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-MacBook ~/dotfiles-MacBook
   cd ~/dotfiles-MacBook
   
   # Linux distros (Fedora, Arch, Debian, openSUSE, Alpine, Gentoo, NixOS)
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-Fedora ~/dotfiles-Fedora
   cd ~/dotfiles-Fedora
   
   # Offense (Kali / WSL2) — a role layer: dotfiles-Debian first (it provisions Kali)
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-Debian ~/dotfiles-Debian
   ~/dotfiles-Debian/bootstrap.sh
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-Offense ~/dotfiles-Offense
   cd ~/dotfiles-Offense
   
   # Defense (defensive role layer) — on top of any OS layer above, installed first
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-Defense ~/dotfiles-Defense
   cd ~/dotfiles-Defense
   

   The role repos install no OS layer of their own: the OS repo's bootstrap.sh must have run before theirs.

   # Windows
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-Windows.git
   cd dotfiles-Windows
   .\install.ps1
   

2. Preview the plan (optional)

   # every repo — macOS, the Linux distros, and the two role repos
   ./bootstrap.sh --links-only --dry-run
   

   All ten bootstraps implement --dry-run.

3. Provision + Wire

   # MacOS
   ./bootstrap.sh
   exec zsh
   
   # Offense / Defense (after the OS layer's bootstrap)
   ./bootstrap.sh
   
   # Linux Distros
   ./bootstrap.sh
   exec zsh
   

   .\install.ps1
   

4. Optional

   # MacOS
   # Apply system defaults
   ./bootstrap.sh --macos-defaults
   
   # Offense (Kali / WSL2)
   # Enable mirrored networking on the windows side
   # Drop dotfiles-Debian/wsl/windows.wslconfig.example at %UserProfile%\.wslconfig,
   # then from Windows:
   wsl.exe --shutdown
   
   # Fedora / openSUSE
   # --no-flatpak
   # skips Flatpak
   
   # Gentoo
   # --no-sync
   # skips the slow emerge --sync on re-runs
   # --no-extras
   # skips the opt-in source builds
   
   # Arch
   # Stage-0 prep in SETUP.md should be run first
   # --no-flatpak
   # skips Flathub/GUI apps (recommended on WSL)
   
   # Alpine
   # run as root or with doas
   # enable the community repo
   

   # Windows
   # set name/email in ~/.gitconfig.local
   wsl --shutdown
   

Usage

Core swaps the classic Unix tools for modern equivalents — but only when they're installed. Detection flags (HAVE_*) are resolved at load time, so every alias falls back to the classic command on a box that doesn't have the newer one. Nothing breaks; things just get nicer where they can.

You type	You get	When present
ls / ll	eza — icons, git status, tree view	eza
cat	bat — syntax highlighting	bat
cd	zoxide — frecency-ranked jumps	zoxide
top	btop	btop
du / df	dust / duf	dust, duf
vim	nvim	always

Run core help (aliased cheat) for the built-in index — a curated one-screen cheat sheet of the function verbs, the most-used git shorthands, the keybindings and the maintenance commands (up, update-check, maint-*, op*). The alias cheat sheet is the complete inventory: every alias in zsh/20-aliases.zsh and the full OMZ-compatible git suite in zsh/25-git.zsh (gst, gcb, glog, gpf, …), plus the function one-liners. Its tables are generated from those files (make gen-aliases) and make audit fails when they drift. The same holds for PORTING-MATRIX.md's generated blocks: two data tables rendered from the sibling OS repos' os/*.capabilities and install/packages.txt, plus one fleet-version table per tool rendered from this repo's own scripts/fleet-package-versions.tsv, all by make gen-porting-matrix — with one qualification: only the two fleet-fed tables need the siblings checked out beside this repo, so on a lone clone (CI included) those record an environment skip rather than a verdict, and scripts/audit-core.sh --require-siblings is what makes the absence red. The in-repo blocks are gated everywhere. The updater and maintenance verbs (up, update-check, maint-*) are also reachable through the front door as core update [check] and core maint <verb>.

For more, see the Documentation.

Contributing

Contributions are greatly appreciated. Because Core is vendored into every OS repo, a change here fans out to all of them — so see CONTRIBUTING.md for what counts as Core, the manifest contract, and the make audit gate. The short version:

1. Fork the project and branch off main
2. Make your change, keeping it Core (identical on every machine, not OS-specific)
3. Run make audit until it's green
4. Open a pull request with a Conventional Commits title

Two companion documents answer what CONTRIBUTING.md deliberately does not: PORTABILITY.md (how to write Core that survives the fan-out) and VENDORING.md (the same contract read from an OS repo's side).

By participating you agree to the Code of Conduct.

Prefer a quick idea? Open an issue with the "enhancement" tag.

Top contributors

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Garrett Allen - @gerrrrt - [email protected] - LinkedIn

Project Link: dotgibson

Acknowledgments

Here are some of my favorite dotfile configurations.

• Neovim (Tony, btw.)
• Dotfiles (omerxx)
• Dotfiles (josean-dev)
• Dotfiles (hendrikmi)