Every dotfiles repo starts the same way: one install.sh, a list of packages, and a cp -r into ~/.config. It works exactly once, on the machine where you wrote it.
Mine broke in the places nobody warns you about:
- A fresh install half-succeeds, then the terminal opens with an error on every prompt.
- Re-running the installer overwrites configs I had edited by hand.
- A package gets renamed upstream, and now the whole script dies at step 3.
- The desktop session is live,
~/.config/hypris briefly empty, and Hyprland panics.
So I stopped trying to write a better installer. I split the job into four scripts that each do one thing, and made every one of them safe to run twice.
That's the whole idea: an installer you run once is a liability. A repair tool you can run any time is an asset.
The four scripts
| Script | Job | Touches your system? |
|---|---|---|
bootstrap.sh | Get a bare Arch install to the point where install.sh can run | Yes — installs git and yay |
install.sh | 4 stages: packages, AUR, configs, shell environment | Yes — backs up first |
doctor.sh | Read-only health check; exit code 1 on failure | No |
repair.sh | Fix a partial install without reinstalling | Yes — only what's broken |
bootstrap is for a machine that doesn't have the repo yet. install is the normal path. doctor tells you what's wrong. repair fixes it.
The important part isn't the number four. It's that installation and diagnosis are separate programs. When they're the same script, the only way to find out what's broken is to run the thing that changes your system.
Lesson 1: read-only beats "just re-run it"
doctor.sh checks, and touches nothing:
- required packages present
- every command
.zshrcdepends on actually resolves on$PATH -
/bin/zshand/usr/bin/zshexist, and zsh is listed in/etc/shells - the login shell is zsh
-
~/.local/bin/envandenv.fishexist - the zsh plugin files are where zsh expects them
- broken symlinks under
~/.config - drift between the repo and the installed configs
It exits non-zero when something required is missing, so it's usable outside a human session:
./doctor.sh || echo "environment is broken — run ./repair.sh" Diagnosis without mutation is the single highest-value thing in the repo. Half the "my dotfiles are broken" posts online are really "I don't know which of forty things is missing."
Lesson 2: idempotent means [SKIP], not "it didn't crash"
repair.sh is designed to be run fifty times. Unchanged state prints [SKIP] and moves on:
==> Step 1/5: Checking required packages... [SKIP] all 12 required packages already installed Two rules make that possible.
Never delete a config directory. cp -r repo/hypr ~/.config/hypr while Hyprland is running can leave the compositor reading a half-written file. Instead, back up and replace file by file, in place:
install_cfg() { local tool="$1" local src="$REPO/$tool/.config/$tool" [ -d "$src" ] || return 0 mkdir -p "$HOME/.config/$tool" while IFS= read -r -d '' file; do local rel="${file#"$src"/}" backup_item "$HOME/.config/$tool/$rel" mkdir -p "$(dirname "$HOME/.config/$tool/$rel")" cp -f "$file" "$HOME/.config/$tool/$rel" done < <(find "$src" -type f -print0) } The directory is never missing, so a live session never sees a hole.
Never run chsh when the shell is already correct. chsh is interactive, needs a password, and fails in scripts. Check first:
ensure_login_shell_is_zsh() { login_shell_is_zsh && return 0 # ... only now change it } Lesson 3: don't fight the distro's package manager
I run Arch with Omarchy. Omarchy enforces a rule: system upgrades go through omarchy update, not pacman -Syu. There's an ALPM hook that will stop you if you try.
My first installer did pacman -Syu --needed <201 packages>. On Omarchy that's not just rude — it's blocked, and it makes the install non-reproducible on a machine that's mid-update.
The fix is to only ever ask for what's missing:
if command -v omarchy-pkg-add &>/dev/null; then omarchy-pkg-add "${official_pkgs[@]}" elif command -v pacman &>/dev/null; then sudo pacman -S --needed --noconfirm "${official_pkgs[@]}" fi 201 official packages, 10 AUR packages, zero upgrades. The distro stays in charge of its own state; the dotfiles repo only fills gaps.
That distinction is worth internalising: installer = converge to a desired state. Upgrader = move the system forward. Mixing them is why "just re-run the installer" has a reputation for breaking systems.
Lesson 4: the dependency that isn't in your package list
This one cost me the most time, and it's invisible in every dotfiles guide.
The last line of my .zshrc sources ~/.local/bin/env. That file isn't created by zsh, by pacman, by mise, or by my repo. It's created by uv's standalone installer. On a fresh machine, every shell start printed:
/home/you/.local/share/../bin/env: No such file or directory Copying .zshrc correctly is not the same as having a working shell. So install.sh and repair.sh both recreate the file with uv's exact template when it's missing:
ensure_local_bin_env() { [ -f "$HOME/.local/bin/env" ] && return 0 mkdir -p "$HOME/.local/bin" uv_env_sh_content > "$HOME/.local/bin/env" chmod +x "$HOME/.local/bin/env" } The general lesson: a shell config has runtime dependencies that aren't packages. Grep your own .zshrc for source and eval "$(... init ...)", and make the installer responsible for every one of them.
Lesson 5: back up before every overwrite, and say where
Every file that gets replaced is copied first into a timestamped directory:
~/.dotfiles-backup/20261114-153012/ Not a cp -r of the whole home directory. Just the specific files about to be touched, preserving paths. The installer prints the path at the end.
That single behaviour turns "I lost my config" into "I lost four minutes." And because the backups are gitignored, they never end up in the repo.
What the whole thing looks like now
bootstrap.sh → fresh Arch: git + yay + clone + hand off to install.sh install.sh → 4 stages, backs up first, never upgrades, validates Hyprland config doctor.sh → read-only, exit 1 on failure, safe in CI repair.sh → idempotent, [SKIP] on unchanged, fixes only what's broken 130 tracked files, including the Hyprland config written in Lua, a custom Quickshell bar plugin, and the terminal, editor, and shell configs. 791 lines of shell across the four scripts.
And the workflow after a reinstall is now:
git clone https://github.com/Aashutosh31/dotfiles.git ~/dotfiles cd ~/dotfiles && ./install.sh # if anything looks off: ./doctor.sh ./repair.sh What I'd do differently
- Write
doctor.shfirst. I wrote it after the third time I couldn't tell why a shell was broken. Every check in it is a bug I hit once. - Keep a required-vs-recommended split.
fzf,uv, andfishare recommended, not required. The installer warns and continues instead of failing, which means it works on machines that aren't mine. - Validate the compositor config, not just the files.
hyprctl configerrorsafter install catches a Lua syntax error that would otherwise show up as a black screen:
if command -v hyprctl &>/dev/null && pgrep -x Hyprland &>/dev/null; then errors="$(hyprctl configerrors 2>/dev/null)" [ -n "$errors" ] && echo "WARNING: $errors" fi - Treat every error message as documentation. The installer now tells you what to run next, not just that something failed.
Steal the structure, not the files
You don't need my theme, my bar, or my keybindings. You need the split:
-
doctor— read-only, exits non-zero, tells the truth. -
repair— idempotent, prints[SKIP], fixes only what's broken. -
install— converges state, never upgrades, backs up every overwrite. -
bootstrap— gets a machine to the point where the other three exist.
If your dotfiles only have step 3, you have an installer. You don't yet have something you can trust on a machine that isn't yours.
