🧬 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. Roadmap
5. Contributing
6. License
7. Contact
8. 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:

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; it was previously shown for macOS only.

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 of every command — it is the complete one. The alias cheat sheet is the curated companion, covering the aliases and the OMZ-compatible git suite (gst, gcb, glog, gpf, …); a handful of function verbs (fif, fbr, up, update-check, maint-*, op*) live only in core help, as do the keybindings.

For more, see the Documentation.

(back to top)

Roadmap

• Add Changelog
• Add back to top links
• Add Additional tools
• README.md overhaul for entire project

See the open issues for a full list of proposed features (and known issues).

(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 the questions CONTRIBUTING.md deliberately does not:

• PORTABILITY.md — how to write Core that survives the fan-out. The bash 3.2 floor, the BSD/busybox coreutils traps, and the shim pattern for reaching an OS capability without naming a path. Read it before your first Core change.
• VENDORING.md — the contract from an OS repo's side. What core/ and core.lock mean, which load-order band your file may claim, and how to send a fix back upstream.

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)