Dotfiles: Version Control Your Environment

Every time you set up a new machine, you have two options. Spend a day and a half reinstalling things, tweaking configs, and trying to remember that one zsh alias you spent twenty minutes perfecting. Or clone a repo and be back to your exact environment in ten minutes.

Dotfiles are how you get the second option.

---

What dotfiles are

Dotfiles are the config files that live in your home directory, named with a leading dot so they stay hidden by default. .zshrc, .gitconfig, .vimrc, .config/nvim/, .ssh/config. Every tool you use has one.

Together they define your environment¹ — how your shell behaves, how your editor looks, what aliases you've built up, how git formats output. They're personal infrastructure. Most developers let them accumulate on a single machine and lose them when something breaks.

Versioning them in a git repo means your environment is reproducible, diffable, and shareable.

---

The naive approach and why it breaks

The obvious move is to make ~ a git repo. It works until it doesn't — git status in your home directory becomes noise, you accidentally commit things you shouldn't, and the repo scope bleeds everywhere.

The slightly better approach is symlinking: keep your dotfiles in ~/dotfiles/, and manually ln -s ~/dotfiles/.zshrc ~/.zshrc for each file. This works. It's also tedious to maintain, easy to forget a file, and annoying to replicate on a new machine².

---

stow

GNU Stow is the standard solution to this. It's a symlink manager — it takes a directory tree and creates symlinks into a target directory³ (your home folder by default), mirroring the structure exactly.

You structure your dotfiles repo like this:

~/dotfiles/
├── zsh/
│   └── .zshrc
├── git/
│   └── .gitconfig
├── nvim/
│   └── .config/
│       └── nvim/
│           └── init.lua
└── ghostty/
    └── .config/
        └── ghostty/
            └── config

Then running:

cd ~/dotfiles
stow zsh

Creates ~/.zshrc → ~/dotfiles/zsh/.zshrc. One command per package. Or stow */ to stow everything at once.

The package structure (one folder per tool) means you can selectively stow only what you need on a given machine — a server gets git and zsh but not nvim or ghostty⁴.

To unstow (remove the symlinks):

stow -D zsh

To restow (useful after moving files around):

stow -R zsh

That's basically the whole API.

---

Setting up from scratch

Install stow — it's in every package manager:

# macOS
brew install stow

# Ubuntu / Debian
apt install stow

Create your dotfiles repo:

mkdir ~/dotfiles
cd ~/dotfiles
git init

Move a config file into the right package folder, then stow it:

mkdir zsh
mv ~/.zshrc zsh/.zshrc
stow zsh
# ~/.zshrc is now a symlink to ~/dotfiles/zsh/.zshrc

Push to GitHub. On a new machine:

git clone git@github.com:you/dotfiles.git ~/dotfiles
cd ~/dotfiles
stow zsh git nvim

Done.

---

What to put in there

The obvious ones: .zshrc / .bashrc, .gitconfig, editor config, terminal config.

A few less obvious ones worth including:

• .gitignore_global — a global gitignore for .DS_Store, .env, editor swap files
• .ssh/config — host aliases and per-host settings (not the keys themselves, obviously)
• shell functions and aliases — if you've split these into separate files sourced from .zshrc
• .config/ghostty/config or whatever terminal you use
• brew bundle — a Brewfile that lists everything installed via Homebrew⁵, so brew bundle restores your packages on a new machine

What to leave out: secrets, tokens, anything machine-specific that shouldn't roam.

---

The compounding return

The lasting benefit is the habit of treating your environment as code⁶. You start reviewing changes before committing them. You write comments explaining why an alias exists. You see the history of how your workflow evolved.

It's also a surprisingly good signal when evaluating tools — if something doesn't have a clean, file-based config, that's worth noting⁷.