From-Scratch Build · Dev Environment
The small, invisible configuration files that quietly run my whole development setup — shell, editor, prompt, git — collected into one repository so a brand-new machine becomes my machine with a single command.
What it is
On a Unix system, almost every tool reads its settings from a hidden file in your home directory — a name that starts with a dot, like .zshrc or .config/nvim/init.lua. These dotfiles are what make a terminal feel like home: the aliases you type without thinking, the colours of your prompt, the key bindings in your editor. Left alone, they scatter across a machine and are forgotten the moment you switch computers.
I built this to solve that problem the way experienced developers do: keep every dotfile in one version-controlled repository, then have a single command lay them down onto any machine. The goal isn't the files themselves — it's reproducibility. A laptop wiped today should look and feel identical tomorrow.
The core idea I wanted to learn: your environment is code. If your shell, editor and tools are described by files in a repo, then setting up a machine stops being an afternoon of clicking and becomes one command you can run, version, and roll back like any other software.
The stack
A dotfiles repo is a cross-section of a working environment. Here are the pieces I configured and why each one earns its place.
The interactive shell — aliases, functions, key bindings, options and environment variables, split into small files so each concern is easy to find and edit.
The editor configured in init.lua. Modern Neovim is scripted in Lua, so the editor's behaviour is real, readable code rather than an opaque settings panel.
A fast, informative command prompt that shows the current directory, git branch and status at a glance — defined in a single declarative config file.
Global git identity, aliases and a shared ignore list, so every repo on the machine inherits the same sensible defaults.
Settings for the everyday command-line tools — search, paging, fuzzy-finding — tuned once and carried everywhere.
The engine that maps repo files to their real home-directory locations and applies them — turning a clone into a fully configured environment.
How it works
The repository doesn't store files at their final paths — it stores a recipe for where each one should go. A small set of naming conventions tells the manager how to translate repo files into a live home directory.
Every config lives in the repo, named by convention so the manager knows a dot_zshrc file becomes ~/.zshrc on the target machine.
Files are symlinked into place, so editing the live file is editing the repo. Changes are never silently lost.
The few things that differ per machine — names, paths, secrets — are filled in from templates at apply time rather than hard-coded.
Sensitive files are stored encrypted in the repo and decrypted only on apply, so a public dotfiles repo never leaks credentials.
First-run scripts install the packages a fresh machine needs, so the environment is complete, not just configured.
Fuller branching for non-macOS machines is left as future work — a reminder that ambitious builds are never quite finished.
How it runs
Bootstrapping is the whole point. The promise of the build is that a freshly imaged laptop, with nothing installed, can be brought to a complete working state by a single line:
In my rebuild I focused on the apply-and-bootstrap path: a single init --apply takes a clean machine to a configured shell, editor and prompt without manual setup.
Reflection