🧬 dotfiles-core

The foundation layer of a cross-platform dotfiles system.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Languages
   • Tools
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Contributing
5. License
6. Contact
7. Acknowledgments

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.

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, nvim, git, starship — identical everywhere
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.

(back to top)

Languages

• 
• 
• 
• 
• 
• 

Tools

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

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
   
   # Offense (Kali / WSL2)
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-Offense ~/dotfiles-Offense
   cd ~/dotfiles-Offense
   
   # Linux distros (Fedora, Arch, openSUSE, Alpine, Gentoo)
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-Fedora ~/dotfiles-Fedora
   cd ~/dotfiles-Fedora

   # 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 nine bootstraps implement --dry-run.

3. Provision + Wire

   # MacOS
   ./bootstrap.sh
   exec zsh
   
   # Offense
   ./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 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
   
   # Arch
   # Stage-0 prep in SETUP.md should be run first
   
   # Alpine
   # run as root or with doas
   # enable the community repo

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

(back to top)

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 two data tables, rendered from the sibling OS repos' os/*.capabilities and install/packages.txt by make gen-porting-matrix — with one qualification: that gate needs the siblings checked out beside this repo, so on a lone clone (CI included) it records an environment skip rather than a verdict, and scripts/audit-core.sh --require-siblings is what makes the absence red. 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.

(back to top)

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

(back to top)

License

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

(back to top)

Contact

Garrett Allen - @gerrrrt - garrettallen2@gmail.com - LinkedIn

Project Link: dotgibson

(back to top)

Acknowledgments

Here are some of my favorite dotfile configurations.

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

(back to top)