dotfiles

Utilizes:

• chezmoi - as dotfile manager
• ansible - for provisioning

Supports:

• Debian
• Fedora
• MacOS
• Windows (wsl)

How this works

Chezmoi:

• Gather one-time input data from the user
• Install package manager and setup ansible
• Install dotfiles - including global scripts, cheatsheets, and more

Ansible:

• Run 1) on first init or 2) if applicable ansible files change
• Install packages, applications, fonts, system configuration (managed outside dotfiles), and more

Philosophy

Long ago, I heavily customized my tools and environments for maximize efficiency. Over time I found that approach slowed me down on shared environments. As a result I now aim for minimal customization across all tooling. In addition, I generally prefer containers over local installs to maintain a more predictable, reproducible, and controlled environment.

Quick start

Optionally use a package manager (recommended) or install chezmoi natively (see Useful Commands).

Apply dotfiles and run applicable ansible playbooks.

export GITHUB_USERNAME=benlinton
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply $GITHUB_USERNAME

For macOS, installs brew if missing. For Windows, installs winget.

Playbook run scenarios

See dot_bootstrap/ for the various playbooks that may automatically run. The ansible installer will run once on init, and the playbooks will run both on init and whenever they are modified.

Scenario	run_once_*.sh	run_onchange_*.sh.tmpl
Fresh machine (init --apply)	Runs (never ran before)	Runs (hash not in state)
Re-apply, playbook unchanged	Skipped	Skipped
Re-apply, playbook edited	Skipped	Runs (hash changed)

Important Pitfall: install_ansible needs to remain alphabetically ahead of provision runner.

Useful commands

Run cheatsheet chezmoi to print useful commands in the terminal.

# Install chezmoi without package manager
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin

# Manually make changes and commits from here
cd ~/.local/share/chezmoi

# Recommended init approach - clones the repo into ~/.local/share/chezmoi/
chezmoi init --apply $GITHUB_USERNAME

# (Optional) Init for non-standard local path - then add sourceDir to the generated chezmoi.toml config
chezmoi init --apply --source /local/path/to/dotfiles

# See what changes would be made
chezmoi diff

# Apply source → home dir 
chezmoi apply <OPTIONAL_PATH>

# Copy home dir edits → source
chezmoi re-add <OPTIONAL_PATH>

# Edit a managed file in place (opens in $EDITOR, applies on save)
chezmoi edit ~/.bashrc

# View the current chezmoi state
chezmoi state dump

# Re-run a run_once script after changes
chezmoi state delete-bucket --bucket=scriptState && chezmoi apply

# Run Ansible playbook manually
ansible-playbook ~/.bootstrap/provision-workstation-macos.yml   # macOS
ansible-playbook ~/.bootstrap/provision-workstation-linux.yml --ask-become-pass  # Linux