dotfiles.pro

Appearance

How to manage your dotfiles across machines ​

You want three things from your dotfiles: a backup, a one-command restore on a new laptop, and a way to keep machines in sync. Most guides get you the first and stop. Here's how to get all three, and the packages, system config, and repos around the files too.

Where most dotfiles setups stop ​

Almost every approach is a rung on the same ladder:

  1. Manual copies: back up .bashrc, .gitconfig, and friends by hand. Fragile, and "sync" means remembering what changed.
  2. A git repo + symlinks: keep your dotfiles in git and symlink them into $HOME (bare git, GNU Stow). Now you have history and one source of truth, for the files.
  3. A dotfiles manager: chezmoi or yadm add per-machine templating and secrets. Still files.

Each rung manages the files in $HOME. None of them installs git, Docker, or your cloud CLIs, or clones your repositories, that's left to a setup.sh you run by hand and forget to update.

The first time a config has to do something, install the tool it configures, render a value that differs per machine, or pull a secret, the symlink stops being enough.

The shift: manage the machine, not just the files ​

Dotfiles Pro takes the next rung: it manages the whole machine with Ansible. You declare the desired state, your identity, the repos to clone, the tools you want, your dotfiles, in a git repository. An apply (one run) reads that, works out what the machine should look like, and applies the difference. (More in Architecture.)

You don't write Ansible to use it, the built-in roles are written for you; you fill in YAML variables, the same YAML you already write for Docker Compose, Kubernetes, and CI.

That reframes the three things you wanted:

  • Backup: your repository, in git. It's the whole machine's definition, not a pile of copied files.
  • Restore: on a new laptop, one apply rebuilds it: packages installed, system configured, repos cloned, dotfiles in place.
  • Sync: re-run the apply. It's idempotent, so it only changes what drifted. Install and update are the same command.

Do it ​

You need a personal repo (your config) that pulls in the Dotfiles Pro collection (the shared roles), and the installer scaffolds one for you.

1. Install. With no repo argument, the installer provisions Ansible, scaffolds a starter repo in ~/.dotfiles, and installs the collection:

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

Already have a personal repo? Pass its URL instead and it clones that: … | sh -s -- git@gitlab.com:yourname/mydotfiles.git.

2. Make it yours. Edit ~/.dotfiles/playbook.yaml, add the roles you want and your vars (git identity, repositories), then push it to your own remote:

yaml
roles:
  # OS base: the matching one runs, the other is skipped (facts decide)
  - 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.docker
  - dotfilespro.roles.dotpro
vars:
  git_config:
    user:
      name: Your Name
      email: you@example.com
  git_repositories:
    .dotfiles: git@gitlab.com:yourname/mydotfiles.git

3. Apply, and preview first. See exactly what will change before it does:

bash
dotpro apply                                   # install + configure this machine
ansible-playbook playbook.yaml --check --diff  # or a dry run that changes nothing

4. Do it again on the next machine. On your second laptop, run the installer with your repo URL (… | sh -s -- git@gitlab.com:yourname/mydotfiles.git) to clone your repo, then dotpro apply. That's your restore and your sync, the same command on every machine.

What you gained ​

Compared with symlinking files, one apply gives you the packages installed, the system configured (services, wsl.conf, locale), your repositories cloned, and your dotfiles in place, all idempotent, all from one reviewed repo. Stop running it and the machine keeps working; nothing dangles.

Next steps ​