/hone

Dotfile Management Strategies

Purpose: Read this when choosing or applying stow, chezmoi, yadm, bare Git, Brewfile, or XDG migration patterns for personal dotfiles.

Contents

• GNU Stow
• chezmoi
• yadm
• Bare Git repository
• Brewfile management
• XDG Base Directory specification
• Selection guide

GNU Stow

Recommended for a single machine or a simple shared layout.

Directory Structure

~/dotfiles/
├── zsh/
│   ├── .zshrc
│   └── .config/
│       └── zsh/
├── nvim/
│   └── .config/
│       └── nvim/
├── ghostty/
│   └── .config/
│       └── ghostty/

Rule: each package mirrors the target path under $HOME.

Commands

stow -d ~/dotfiles -t ~ zsh
cd ~/dotfiles && stow */
stow -d ~/dotfiles -t ~ -D zsh
stow -d ~/dotfiles -t ~ -R zsh
stow -d ~/dotfiles -t ~ -n -v zsh

.stow-local-ignore

\.git
\.gitignore
\.gitmodules
README\.md
LICENSE
^\.DS_Store

Multi-Machine Pattern

~/dotfiles/
├── zsh/
├── nvim/
├── zsh-work/
├── zsh-personal/
└── linux-specific/

cd ~/dotfiles && stow zsh nvim zsh-work

chezmoi

Recommended for multiple machines, template logic, or secret integration.

Workflow

chezmoi init
chezmoi add ~/.zshrc
chezmoi edit ~/.zshrc
chezmoi diff
chezmoi apply

Go Template Example

{{ if eq .chezmoi.os "darwin" -}}
eval "$(/opt/homebrew/bin/brew shellenv)"
{{ end -}}

Config Example

[data]
    name = "Your Name"
    email = "{{ if eq .chezmoi.hostname "work-laptop" }}work@company.com{{ else }}personal@email.com{{ end }}"

Secret Management

{{ onepasswordRead "op://vault/item/field" }}
{{ (bitwarden "item" "My SSH Key").notes }}
chezmoi add --encrypt ~/.ssh/id_rsa
{{ (keyring "service-name" "username") }}

Naming Conventions

yadm

Basic Workflow

yadm init
yadm add ~/.zshrc ~/.config/nvim/init.lua
yadm commit -m "initial dotfiles"
yadm remote add origin <repo-url>
yadm push -u origin main

yadm clone <repo-url>

Alt Files

~/.config/zsh/aliases.zsh##os.Darwin
~/.config/zsh/aliases.zsh##os.Linux
~/.config/zsh/aliases.zsh##h.work-laptop
~/.config/zsh/aliases.zsh##default

Bootstrap Script

#!/bin/bash

if ! command -v brew &>/dev/null; then
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi

brew bundle --file="$HOME/Brewfile"
nvim --headless "+Lazy! sync" +qa

Bare Git Repository

Minimal approach when you want Git only and no templates.

Setup

git init --bare $HOME/.dotfiles
alias dotfiles='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
dotfiles config --local status.showUntrackedFiles no

Workflow

dotfiles add ~/.zshrc
dotfiles commit -m "add zshrc"
dotfiles push

git clone --bare <repo-url> $HOME/.dotfiles
dotfiles checkout

Limitation: no templates, no secret management, and weak multi-machine support.

Brewfile Management

Structure

tap "homebrew/bundle"
tap "homebrew/cask-fonts"

brew "git"
brew "neovim"
brew "tmux"
brew "starship"
brew "sheldon"
brew "mise"
brew "ripgrep"
brew "fd"

Commands

brew bundle
brew bundle --file=~/dotfiles/Brewfile
brew bundle dump --force
brew bundle check
brew bundle cleanup
brew bundle cleanup --force

Tips

• Keep Brewfile in the dotfiles repo.
• Prefer brew bundle dump --describe when you want comments.
• Split Brewfile and Brewfile.work if machines differ.
• Run brew bundle check in bootstrap scripts or CI.

XDG Base Directory Specification

Variables

Tool Support

Migration Steps

export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"
export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"

export ZDOTDIR="$XDG_CONFIG_HOME/zsh"
mkdir -p "$XDG_CONFIG_HOME" "$XDG_DATA_HOME" "$XDG_STATE_HOME" "$XDG_CACHE_HOME"

Selection Guide

Decision Flow

Need machine-specific configs?
├── Yes -> Need secrets management?
│   ├── Yes -> chezmoi
│   └── No -> chezmoi or yadm
└── No -> Need more than ~10 config files?
    ├── Yes -> GNU Stow
    └── No -> Manual symlinks or bare Git

Output Routing Table (SKILL.md excerpt)

Routing rules:

• If the request mentions shell or startup time, read reference/personal-environment/shell-configs.md.
• If the request mentions editor or neovim, read reference/personal-environment/editor-configs.md.
• If the request mentions audit or anti-patterns, read the relevant anti-pattern reference.
• Always run SCAN phase before making changes.