You’ve put real effort into that setup by now. The .zshrc you finally understand, the tmux config, the Starship prompt — hours of tuning, all of it sitting on exactly one machine, one fat-fingered rm or dead SSD away from oblivion. And when the next machine arrives, you’ll recreate it from memory, badly, over about a month.

Dotfiles are code, and code belongs in version control. The good news: if you have git, you already have everything you need.

Section titled “What to track (and what to keep out)”

Worth tracking:

Section titled “Three ways to do it”

Approach Extra tooling Best for

Bare git repo None — just git Most people; one config set, minimal fuss

GNU Stow stow Symlink tidiness; one package directory per app

chezmoi chezmoi Multiple machines, per-OS differences, secrets

The honest recommendation: start with the bare repo. It takes five minutes, uses tooling you already trust, and you can graduate to chezmoi later without losing anything.

Section titled “The bare-repo method”

The trick is a bare repository — one with no working tree of its own — because your entire home directory plays that role. No symlinks, no copying files into place; the real ~/.zshrc is the tracked file.

git init --bare -b main ~/.dotfiles

Add an alias so you can talk to it, and put the same line in your ~/.zshrc so it survives. Call it dotfiles, or dots, or anything but git, for reasons that should be obvious:

alias dotfiles='git --git-dir=$HOME/.dotfiles --work-tree=$HOME'

Stop git helpfully reporting that your entire home directory — all several hundred thousand files of it — is untracked:

dotfiles config --local status.showUntrackedFiles no

Track your first files:

dotfiles add ~/.zshrc ~/.tmux.conf ~/.config/starship.toml

dotfiles commit -m "Initial dotfiles"

Push to a private GitHub repo — private, because dotfiles have a way of accumulating things you’d rather not open-source:

dotfiles remote add origin [email protected]:you/dotfiles.git

dotfiles push -u origin main

Day to day, it’s ordinary git with a funny name — and unlike ordinary git, it works from any directory, because the work tree is always your home:

dotfiles status

dotfiles add ~/.zshrc

dotfiles commit -m "Tweak history settings"

dotfiles push

Caution

Always name files explicitly when adding. dotfiles add -A does not respect showUntrackedFiles no and will happily start staging your home directory — Downloads, Steam library, everything. That’s a story you don’t want to tell.

Section titled “Setting up a new machine”

This is the moment the whole exercise exists for:

git clone --bare [email protected]:you/dotfiles.git ~/.dotfiles

alias dotfiles='git --git-dir=$HOME/.dotfiles --work-tree=$HOME'

dotfiles checkout

dotfiles config --local status.showUntrackedFiles no

One gotcha: if the machine already has a stock ~/.zshrc, git quite reasonably refuses to trample it — error: The following untracked working tree files would be overwritten by checkout. Move the offenders aside (mv ~/.zshrc ~/.zshrc.stock) and re-run the checkout. Then add the alias to your freshly checked out .zshrc, which is a pleasingly circular way to finish.

Section titled “Keeping secrets out”

Some config inevitably references things that can’t be committed. The pattern is the same everywhere: track the file, source an untracked local sibling.

For git itself, use an include — the same mechanism that lets a .gitconfig pick your work email by directory:

~/.gitconfig (tracked)

[include]

path = ~/.gitconfig.local

For the shell:

~/.zshrc (tracked)

[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local

Project secrets follow the same pattern a level down: direnv loads an untracked .env from a committed .envrc, and only while you’re in that project.

And if a secret ever does land in a commit: rotate it immediately. Deleting the file in a later commit doesn’t remove it from history, and “private repo” is a comfort blanket, not a vault.

Section titled “When you outgrow it”

chezmoi is the full-service option: templating for per-machine and per-OS differences ({{ if eq .chezmoi.os "darwin" }} and friends), and proper integrations for pulling secrets from a password manager at apply time. Written in Go, because the Rust toolchain can’t compile everything.

brew install chezmoi

chezmoi init

chezmoi add ~/.zshrc

later, on a new machine:

chezmoi init --apply [email protected]:you/dotfiles.git

If “work laptop versus personal machine versus a homelab box running Debian” describes your life, chezmoi earns its install. If that sentence didn’t describe you, the bare repo is enough.

GNU Stow has been managing symlink farms since the early nineties and remains better at it than most of what came after. Configs live in per-app package directories; stow zsh symlinks the package into place:

mkdir -p ~/dotfiles/zsh

mv ~/.zshrc ~/dotfiles/zsh/

cd ~/dotfiles && stow zsh # ~/.zshrc is now a symlink into the repo

Worth it if you like each app’s config in its own directory and don’t mind living life symlinked.

Section titled “Where next”

Your setup is now one git clone away from immortal. If any of the files mentioned above don’t exist yet, that’s what the rest of the site is for: the .zshrc, the .gitconfig, the tmux config, the Starship prompt, and a terminal worth configuring in the first place.