Dotfiles Pro

System and dotfiles manager for Ubuntu, macOS, and WSL, powered by Ansible. It installs and configures tools, clones repositories, and sets up shell aliases — the whole machine, not just the files in $HOME.

📖 Full documentation → dotfiles.pro

Demo

The day-2 loop on a converged machine with a couple of changes pending: dotpro plan previews them, dotpro apply converges (a starship release upgrade and a new alias), and dotpro versions shows the upgrade landing in the history. The recording is scripted (roles/dotpro/record-demo.sh replays it in a disposable container), so it regenerates instead of drifting; shown at 2x speed:

Why Ansible?

A developer laptop is the last long-lived, mutable, personal machine in the stack — exactly what configuration management is for:

• One tool for the whole machine — packages, system config, repositories, and dotfiles; no symlink manager plus an imperative setup.sh for the rest.
• Settings, not files — roles write only the keys you declare, so software updates keep their improved defaults instead of fighting your dotfiles.
• Idempotent and incremental — re-run anytime, target one role with --tags, preview with --diff; reinstall and update are the same code path.
• Scales from one laptop to a fleet — the same repo layout serves a personal machine and a 20-person company.

See alternatives for how this compares to chezmoi, Nix home-manager, MDM, and devcontainers.

Roles

Role	Description
ubuntu	System updates, locale, ~/.profile.d/ shell framework, bash aliases
macos	System setup via Homebrew, macOS defaults and Dock; imports the unix shell framework
unix	OS-neutral base every platform role imports: ~/.profile.d/ framework, generic aliases
bash	Shared alias / script / version-recording helpers other roles import
zsh	The zsh shell role (completions via compinit); unix selects it on macOS
ssh	Keychain SSH key loading and ~/.ssh/config host aliases
ansible	Ansible itself and aliases
dotpro	The dotpro CLI for the install/apply workflow
dotfiles	Link, copy, or template raw dotfiles into $HOME, with backup and pruning
git	Git config, pre-commit, 20+ git aliases, repository cloning
github	gh CLI, PR/issue/run aliases
gitlab	glab CLI, MR/issue/pipeline aliases
starship	starship.rs prompt with k8s/terraform/docker/AWS context
nerdfonts	Nerd Fonts installed system-wide
terraform	Terraform CLI
opentofu	OpenTofu CLI and 20+ aliases
docker	Docker and Docker Compose
kubernetes	kubectl, kubeseal, k9s and 25+ aliases
claude	Claude CLI
agents	Shared ~/AGENTS.md AI agent instructions
bitwarden	Bitwarden CLI
python	Python tooling
googlecloud	Google Cloud CLI
digitalocean	doctl CLI
aws	AWS CLI and AWSume
wsl	wslu utilities, wsl.conf and .wslconfig, WSL-specific aliases
windows	Windows itself from WSL: winget packages, registry, virtual desktops, workspace launchers

Quick start

Bootstrap a machine from your personal dotfiles repo:

curl -LsSf https://dotfiles.pro/install.sh | sh -s -- git@gitlab.com:yourname/mydotfiles.git

It provisions Ansible via uv (or Ubuntu 24.04+ system packages with DOTPRO_ANSIBLE_METHOD=apt), clones your repo, and installs the collection. Then review and apply the host:

dotpro apply

(Or bootstrap and apply in one shot with DOTPRO_APPLY=1.) Prefer to wire it up by hand?

sudo apt install ansible ansible-mitogen
git clone git@gitlab.com:yourname/mydotfiles.git ~/.dotfiles
cd ~/.dotfiles
ansible-galaxy collection install -r requirements.yml
ansible-playbook playbook.yaml --ask-become-pass

Copy a starter from examples/: single (one machine), multiple (a few, one inventory), or many (many machines, with group_vars/host_vars). They differ in where vars live and how roles vary per machine — one play per host for a few, roles-as-data for many (see Configuration).

Documentation

• Getting started — install and first run
• Configuration — organize config; different roles per machine
• Roles — what each role does, conventions, and adding your own
• Contributing — fork, test, and open a merge request
• Plugins — third-party roles that compose
• Alternatives — vs chezmoi, Nix, MDM, devcontainers

License

MIT