Skip to content

dotfiles

Setting up a new computer: clone. run. done.

The one repo cloned onto every machine — Mac, Linux, or WSL2 — and built to be forked. A GNU Stow symlink farm with a single source of truth, driven by an idempotent Python installer that is careful never to fight the machine it is setting up.

install.sh converging a fresh Mac — Homebrew, the Stow symlink farm, macOS defaults, and the privileged setup, run idempotently.

Quick start

There is no toolchain to install first — install.sh bootstraps Homebrew and uv itself, then hands off to the installer.

git clone https://github.com/nivintw/dotfiles ~/dotfiles
~/dotfiles/install.sh

That one command converges a fresh machine to the declared setup: CLI tools, fish (zsh is a selectable opt-in — install.sh --shell zsh), and — on macOS — GUI apps, the MesloLGS NF font, the macOS defaults, and the Dock. On Linux and WSL2 the same OS-agnostic core runs and the macOS-only phases skip themselves. It is safe to re-run: it converges the machine to the declared state rather than clobbering what is already there.

Forking?

install.sh installs one person's taste — package list, Dock, keys, macOS defaults. Review and edit those before running it. See Make it yours.

Explore

  • Getting Started

    Clone, run, and what the bootstrap does — phase by phase — plus how to make the repo yours.

  • Architecture

    A symlink farm with one source of truth, an OS-gated phase registry, and overlays that keep machine-specific state out of the tracked repo.

  • The Stack

    The CLI tools, shells, and apps the dotfiles set up — and why each earns its place.

  • Commands

    The custom fish functions the repo ships: what each does, how to invoke it, and its caveats.

  • Quality

    The prek hook suite, pytest + bats tests, and the CI installer-smoke jobs that run install.sh end-to-end on real macOS and Linux runners.

  • Security

    Secret hygiene, pinned supply-chain binaries, and the tamper gate that keeps the pins honest.

What makes it tick

Feature What it gives you
GNU Stow home/ mirrors $HOME via symlinks — editing ~/.config/fish/config.fish edits the repo file directly, with no copy or apply step.
Idempotent bootstrap Re-run install.sh anytime; it adopts existing packages and symlinks instead of clobbering them, converging the machine to the declared state.
Machine-local overlays One branch across every machine — work box, homelab, personal — with nothing machine-specific leaking into the public repo.
Quality gate A prek hook suite plus bats and pytest, run identically locally and in CI, with installer-smoke jobs that run install.sh --core end-to-end on ephemeral macOS and Linux runners.
Local AI fleet Role-based Ollama models provisioned by the installer; the ollm CLI routes mechanical work to them, and a session-start hook shows Claude Code the live roster.