Skip to content
Velloreth
Developer Tools 9 min read

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

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?

IncludeExclude
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, lazygitFiles that change constantly (history, recents)
Package lists for your OSnode_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.

ApproachBest whenCost
Plain scriptYou have ten files and one OSYou maintain every line
StowYou want symlinks with no frameworkDirectory conflicts, GNU dependency
chezmoiMultiple OSes, templating, secretsNew tool and its conventions
yadmYou want git to be the whole storyHome 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:

  1. Inventory what exists. ls -la ~ and ls -la ~/.config will show you more than you remember — including files you forgot were customized.
  2. Read the candidates. Open each file you are considering. Anything you do not understand is a candidate for leaving alone, not for committing.
  3. 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
  4. Trim machine-specific lines as you go — the PATH entry for that one project, the alias for a client’s server, the credentials you did not realize were inline.
  5. 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 -sf overwrites; package managers skip what is installed.
  • Explicit about failure. set -euo pipefail stops 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 .gitignore and holds your exports.
  • Secret manager. chezmoi plus op read op://Vault/item/field, or pass, keeps the secret in the vault and writes it to disk at apply time.
  • Never commit: SSH private keys, cloud credentials, .env files 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 — pbcopy versus xclip versus wl-copy).
  • Branch by hostname in yadm, or keep separate override files per machine.
  • Local overrides for everything else. Work proxies, specific PATH entries, 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.

Frequently asked questions

What exactly belongs in a dotfiles repository?
Shell configuration, git config, editor settings, terminal emulator config, and tool configs like ripgrep, bat, and tmux. Anything you would want on a new laptop within the first hour of working on it.
Should I use Stow or chezmoi?
Stow if you want simple symlinks and full control over every file. chezmoi if you need to handle multiple operating systems, template files per machine, or manage secrets — it does more, at the cost of learning its conventions.
Is it safe to put my whole home directory in git?
No. Commit only configuration you have read and understood, keep it in a private repository, and exclude anything containing tokens, keys, hostnames you should not publish, or state that changes constantly like shell history.
How do I sync dotfiles between work and personal machines?
Push to a private remote and pull on the other machine, then re-run your apply step (stow, chezmoi apply, or your script). Keep machine-specific overrides in gitignored local files so the two setups can diverge without conflicts.