dotfiles.proAnsible powered

Quick start ​

One command bootstraps a machine: it ensures a new-enough Ansible, clones your dotfiles repo (or scaffolds a starter if you don't have one yet), and installs the Dotfiles Pro collection. Then dotpro apply converges the machine. It's the same command for every update.

Read the installer before you pipe it to a shell:

curl -LsSf https://dotfiles.pro/install.sh | less

Then run it against your own dotfiles repo:

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

Or with no repo yet, to scaffold a starter in ~/.dotfiles:

curl -LsSf https://dotfiles.pro/install.sh | sh

Start from the one-machine example and go to multiple machines from there.

How it works ​

Get the collection ​

Your personal repo references it in requirements.yml:

collections:
  - name: dotfilespro.roles

Declare your roles ​

List the roles to run in playbook.yaml. The OS base is picked per machine from facts (ubuntu on Linux and WSL, macos on a Mac), so one file runs unchanged across all your machines. Add the roles you want, then override defaults with your own vars (git identity, repositories, aliases):

- hosts: localhost
  connection: local
  roles:
    - role: dotfilespro.roles.ubuntu
      when: ansible_facts.os_family == 'Debian'
    - role: dotfilespro.roles.macos
      when: ansible_facts.os_family == 'Darwin'
    - dotfilespro.roles.git
    - dotfilespro.roles.kubernetes

Configure your settings ​

Declare only the settings you want under vars; everything else keeps the tool's own defaults. Your git identity and repositories are the usual starting point:

- hosts: localhost
  # ...
  vars:
    git_config:
      user:
        name: Your Name
        email: you@example.com
    git_repositories:
      .dotfiles:
        repository: git@gitlab.com:yourname/mydotfiles.git
        path: ~/.dotfiles

Apply, and re-apply ​

The first run and every later update are the same command. It's idempotent, so a re-run only touches what drifted. Preview with dotpro plan, target one role with dotpro tags <role>:

dotpro apply

dotpro apply                   # ansible-playbook playbook.yaml --ask-become-pass
dotpro plan                    # ansible-playbook playbook.yaml --check --diff
dotpro tags git                # ansible-playbook playbook.yaml --tags git
dotpro tags                    # ansible-playbook playbook.yaml --list-tags
dotpro vars                    # ansible-inventory --host $(hostname) --yaml
dotpro requirements --upgrade  # ansible-galaxy collection install -r requirements.yml --upgrade

Getting started → walks through the full setup.

Highlights ​

A short tour of the everyday wins, the aliases, functions, and prompts that make a managed machine a pleasure to use. The highlights page covers each one in full; here is the whole list.

Set up and keep a machine up-to-date ​

• One command sets up a whole machine
• Bootstrap a machine that has no SSH key yet
• Keep a machine up-to-date on a schedule
• Re-apply just your settings in seconds
• Know exactly what an update changed
• Every run is on the record

Everyday shell ​

• A shell framework you never edit by hand
• One alias per project that sets the whole scene
• Discover every command you have

Everyday git ​

• Clone every project on a fresh machine
• See every repo's status at once
• Get to know a codebase in one command
• Per-directory git identity, no manual switching
• Git defaults you would otherwise set by hand

Cloud and Kubernetes context ​

• Switch clusters and namespaces without juggling files
• A gcloud account that stays put
• A terminal per task, no crossed wires
• Preview a Helm upgrade before you apply it
• A prompt that always tells you where you are

WSL ​

• Reach the Windows side from the WSL shell
• Lens on Windows, gcloud in WSL
• Windows workspaces

Security ​

• Type your SSH passphrase once
• Keep secrets in Bitwarden, not in your repo
• A strong password on demand

See all highlights →

Why another dotfiles manager? ​

Servers stopped needing configuration management when they became disposable, rebuilt from images, orchestrated by Kubernetes. A developer laptop is the opposite: the last long-lived, mutable, personal machine in the stack, the one that can't be containerized because it's where the containers run.

Keeping such a machine up-to-date over time is exactly the problem configuration management was built for.

Most dotfiles tools manage the files in $HOME. This manages the whole machine (packages, system config, repositories, and dotfiles) on the configuration-management engine built for long-lived hosts. It's scored against chezmoi, yadm, Nix home-manager, Stow, dotbot, bare git, Salt, Puppet, Chef, MDM, devcontainers, and golden images, on each one's own terms.

See the comparisons →