Dotfiles Setup: A Reproducible Dev Environment
Build a dotfiles repository you can apply to any machine in minutes — repo layout, Stow vs chezmoi vs yadm, bootstrap scripts, and keeping secrets out of git.
By Velloreth
A development environment you can rebuild in an hour is worth more than one you have spent four years tuning. Machines die, jobs issue laptops, operating systems get reinstalled — and every time, the same question comes up: what exactly was in my shell config?
Dotfiles are the answer. They are the small configuration files in your home directory (.bashrc, .gitconfig, .vimrc) collected into a version-controlled repository, with a repeatable way to apply them to any machine.
This is how I structure that repository, what I let it manage, and the mistakes that turn a clean setup into a maintenance headache.
What belongs in the repo
The test is simple: would you want this file present within the first hour on a new machine?
| Include | Exclude |
|---|---|
Shell config (.zshrc, .bashrc, aliases, functions) | Secrets, API tokens, SSH private keys |
| Git config (aliases, signing setup, ignore rules) | Shell history, package caches, logs |
| Editor config (Neovim, VS Code settings and keymaps) | Machine-specific absolute paths (/home/oldname/...) |
| Terminal emulator config (Ghostty, Kitty, Alacritty) | Anything with credentials in it, even “temporarily” |
| Tool configs: ripgrep, bat, fzf, delta, tmux, lazygit | Files that change constantly (history, recents) |
| Package lists for your OS | node_modules, build output, generated files |
Two rules cover most of the risk. First, read every file you commit — dotfile repos leak tokens with alarming regularity. Second, prefer configuration over state: a file that declares how a tool behaves belongs in git; a file that records what you did last Tuesday does not.
Repository layout
A structure that scales past a dozen files looks like this:
~/dotfiles/
├── README.md
├── bootstrap.sh
├── install.sh
├── packages/
│ ├── brew.txt
│ ├── apt.txt
│ └── cargo.txt
└── home/
├── .bashrc
├── .zshrc
├── .gitconfig
├── .config/
│ ├── bat/config
│ ├── ghostty/config
│ ├── ripgrep/ripgreprc
│ ├── nvim/
│ └── tmux/tmux.conf
└── .local/
└── bin/
└── repo-stats
Two decisions inside that tree matter.
Mirror the home directory. Keeping home/.config/bat/config at the same relative path as ~/.config/bat/config makes whatever tool you use trivially predictable. No mapping table, no guesswork about where a file lands.
Use XDG directories. Tools that support XDG_CONFIG_HOME keep their config in ~/.config instead of scattering dotfiles across $HOME. That shrinks the surface area you have to manage and makes the “exclude” list smaller.
Three ways to apply it
You have three realistic options, plus the zero-dependency fallback.
Plain script
The simplest approach: a script that copies or symlinks files into place.
#!/usr/bin/env bash
set -euo pipefail
DOTFILES="$HOME/dotfiles/home"
ln -sf "$DOTFILES/.zshrc" "$HOME/.zshrc"
ln -sf "$DOTFILES/.gitconfig" "$HOME/.gitconfig"
mkdir -p "$HOME/.config"
ln -sfn "$DOTFILES/.config/nvim" "$HOME/.config/nvim"
You write the mapping yourself, which means you understand every line. It also means you write the same ln -sf line for every new tool forever.
GNU Stow
Stow builds the symlinks for you. Your repo becomes a set of “packages”, and stow links their contents into $HOME:
cd ~/dotfiles
stow -n -v home # dry run: show what would be linked
stow home # create the symlinks
stow -D home # unlink everything Stow created
Stow is one small GNU dependency, works anywhere, and its dry-run mode makes it easy to see what a change will do before you do it. Its known annoyance is directory conflicts when two packages both want to own ~/.config — Stow’s “folding” behavior handles it, but you will hit the concept eventually.
chezmoi
chezmoi treats your home directory as a managed target. Source files live in ~/.local/share/chezmoi, names like dot_zshrc map to ~/.zshrc, and chezmoi apply reconciles everything.
Where it earns its complexity is templating:
{{ if eq .chezmoi.os "darwin" }}
export PATH="/opt/homebrew/bin:$PATH"
{{ else if eq .chezmoi.os "linux" }}
export PATH="$HOME/.local/bin:$PATH"
{{ end }}
One source file now serves your Mac and your Linux box. chezmoi also integrates with secret managers (1Password’s op, age, pass) so an encrypted secret can land on disk without ever entering git.
yadm
yadm is dotfiles-as-git: your $HOME itself is the worktree of a bare repository, with hostname-based branches for machine differences and optional GPG encryption for individual files. If your mental model is “git, but for my home directory,” it fits.
| Approach | Best when | Cost |
|---|---|---|
| Plain script | You have ten files and one OS | You maintain every line |
| Stow | You want symlinks with no framework | Directory conflicts, GNU dependency |
| chezmoi | Multiple OSes, templating, secrets | New tool and its conventions |
| yadm | You want git to be the whole story | Home directory is the repo; steeper git usage |
Pick the lightest one that solves your actual problem. Moving from a script to Stow is a small step; moving to chezmoi is a real decision.
Migrating the machine you already have
Starting from scratch is the easy case. Most people begin with a home directory that has four years of accumulated config, and the temptation is to overwrite it with a pristine repo and lose whatever was actually tuned.
Do it in reverse instead:
- Inventory what exists.
ls -la ~andls -la ~/.configwill show you more than you remember — including files you forgot were customized. - Read the candidates. Open each file you are considering. Anything you do not understand is a candidate for leaving alone, not for committing.
- Copy into the repo, do not link yet. Put the real file into
home/, then compare it with what is at the original location:diff home/.zshrc ~/.zshrc - Trim machine-specific lines as you go — the
PATHentry for that one project, the alias for a client’s server, the credentials you did not realize were inline. - Link only after the diff is clean. Now
stow(or your script) replaces the original with a symlink to the copy you just verified.
The important habit is the diff. A dotfiles migration that skips comparison is how people end up silently losing an alias they used twenty times a day and cannot figure out why.
Package lists deserve the same treatment. Capture what is already installed before you write the bootstrap:
brew leaves > packages/brew.txt # top-level brew packages only
apt-mark manual > packages/apt.txt # manually installed apt packages
cargo install --list | awk '{print $1"@"$2}' > packages/cargo.txt
brew leaves matters more than brew list — it records the packages you chose, not the hundreds pulled in as dependencies. Otherwise your “install list” becomes a mirror of your old machine’s entire history.
The bootstrap script
The point of dotfiles is the first hour on a new machine. That means one entry point:
#!/usr/bin/env bash
set -euo pipefail
DOTFILES_REPO="git@github.com:you/dotfiles.git"
DOTFILES="$HOME/dotfiles"
if [[ ! -d "$DOTFILES" ]]; then
git clone "$DOTFILES_REPO" "$DOTFILES"
fi
# install packages for this OS
if command -v brew >/dev/null 2>&1; then
brew bundle --file "$DOTFILES/packages/brew.txt"
elif command -v apt-get >/dev/null 2>&1; then
xargs -a "$DOTFILES/packages/apt.txt" sudo apt-get install -y
fi
# apply configuration
cd "$DOTFILES"
stow home
echo "Done. Open a new shell to pick up changes."
Three properties make a bootstrap script trustworthy:
- Idempotent. Running it twice is safe. Cloning checks for the directory first;
ln -sfoverwrites; package managers skip what is installed. - Explicit about failure.
set -euo pipefailstops at the first error instead of continuing halfway and leaving a broken environment. - OS-aware. Branch on what is available (
command -v), not on hostname guesses.
Secrets never go in git
This is the part people skip and regret. Tokens in a dotfile repo end up in forks, in CI logs, and in your git history long after you think you deleted them.
The workable patterns:
- Gitignored local files. Commit
.zshrc, and at the end of it source$HOME/.zshrc.local— which is in.gitignoreand holds your exports. - Secret manager. chezmoi plus
op read op://Vault/item/field, orpass, keeps the secret in the vault and writes it to disk at apply time. - Never commit: SSH private keys, cloud credentials,
.envfiles with real values, personal access tokens, and anything that identifies a client or employer.
If a token has ever been committed, treat it as leaked. Rotate it, then clean history — history rewriting is a separate, riskier job, and rotation is the part that actually protects you.
Handling machine differences
Work and personal machines diverge. Fights with your own dotfiles come from pretending they will not.
- Template by OS where behavior differs (package paths, clipboard commands —
pbcopyversusxclipversuswl-copy). - Branch by hostname in yadm, or keep separate override files per machine.
- Local overrides for everything else. Work proxies, specific
PATHentries, and employer-specific git identity go into gitignored local files.
The main repo should express what the machines share. Everything else is an override, and overrides are allowed.
Test it like you mean it
An untested bootstrap script is a guess. The cheap way to know it works is to run it where nothing else exists:
docker run -it ubuntu:24.04 bash
apt-get update && apt-get install -y git curl
git clone git@github.com:you/dotfiles.git ~/dotfiles
cd ~/dotfiles && bash bootstrap.sh
Also worth automating on the repo itself: scan for absolute paths that reference a specific machine before committing.
rg -n '/home/[a-z]+/' home/ --glob '!*.local*'
Run the container test every few months, not just when you need it. The failure you find in a container is the failure you would have hit on a work laptop with a deadline attached.
The daily loop
The maintenance side is deliberately boring: change a config in your editor, use it for a day, then commit it.
cd ~/dotfiles
git add home/.config/bat/config
git commit -m "bat: switch to gruvbox-dark"
git push
On the other machine, pull and re-run your apply step. That is the whole sync model — git, plus one command.
Two maintenance habits keep it healthy. First, write the README as you go: which command applies the config, how secrets are handled, what the override files are for. Future you, arriving at a fresh laptop at 9am, is not going to reconstruct your design decisions from the file tree. Second, review your own repo occasionally the way you would review anyone else’s — git log --stat will show you config you added and never meant to make permanent, and a file that has not been touched in two years is a file worth questioning.
The payoff is not the setup itself. It is that the next machine costs an afternoon instead of a week, and that your environment stops being tribal knowledge living in one person’s head.