🧬 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-Kali, dotfiles-Defense	offensive / defensive tooling

The rationale (why subtree, 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

All you need up front is Git and your platform's base toolchain — bootstrap.sh provisions everything else (zsh, tmux, nvim, starship, and friends). 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
   
   # Kali
   git clone --branch vX.Y.Z https://github.com/dotgibson/dotfiles-Kali ~/dotfiles-Kali
   cd ~/dotfiles-Kali
   
   # 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)

   # MacOS
   ./bootstrap.sh --links-only --dry-run
   
   # Linux distros (Fedora, Arch, openSUSE, Alpine, Gentoo)
   ./bootstrap.sh --links-only

3. Provision + Wire

   # MacOS
   ./bootstrap.sh
   exec zsh
   
   # Kali
   ./bootstrap.sh
   
   # Linux Distros
   ./bootstrap.sh
   exec zsh

   .\install.ps1

4. Optional

   # MacOS
   # Apply system defaults
   ./bootstrap.sh --macos-defaults
   
   # Kali
   # 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, or browse the full alias cheat sheet — including the OMZ-compatible git suite (gst, gcb, glog, gpf, …).

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

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 - [email protected] - 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)