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 — 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 and 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
• One hotkey per client: 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 →