Platforms and profiles

A single dotfiles repo can be used on different operating systems and in different modes. Arch and macOS use different package managers. Two machines may need different services. One laptop may have both a personal profile and a work profile.

dots exposes platform facts while dots.lua runs. It also exposes dots.profile, which can be selected from the command line.

Platform facts

Use dots.platform for OS and distro decisions:

if dots.platform.family == "arch" then
  dots.yay.enable({ method = "aur" })
  dots.yay.install({ "bat", "ripgrep" })
end

if dots.platform.family == "darwin" then
  dots.brew.enable()
  dots.brew.install({ "bat", "ripgrep" })
end

Available fields:

Field	Example
dots.platform.system	x86_64-linux
dots.platform.arch	x86_64
dots.platform.os	linux
dots.platform.distro	arch, ubuntu
dots.platform.family	arch, debian
dots.platform.hostname	thinkpad

system uses the Nix-style shape <arch>-<os>, such as x86_64-linux or aarch64-darwin.

family values:

Distros	family	Packages
Arch, EndeavourOS	arch	dots.pacman
Debian, Ubuntu, Pop!_OS	debian	dots.apt
Fedora, RHEL, CentOS, Rocky, Alma	fedora	dots.dnf
openSUSE, SLES	suse	dots.zypper
Alpine	alpine	dots.apk
macOS	darwin	dots.brew

Profiles

Use profiles for choices that are not determined by the operating system. For example, the same laptop can use a work Git config during the day and a personal Git config outside work:

if dots.profile == "work" then
  dots.symlink("~/.gitconfig", "profiles/work/gitconfig")
end

if dots.profile == "personal" then
  dots.symlink("~/.gitconfig", "profiles/personal/gitconfig")
end

Select a profile on the command line:

dots --profile work check
dots --profile work apply

Or with an environment variable:

DOTS_PROFILE=work dots check

If no profile is selected, dots.profile defaults to the hostname.

Shared resources and cleanup

Applying a profile records it as an owner of each resource it declares, even if nothing needs changing. Resources owned only by other profiles stay untouched.

Profiles can own the same resource. In the Git example above, applying work points ~/.gitconfig at the work source. Applying personal points it at the personal source. Both profiles remain owners.

If you remove a declaration and apply that profile again:

• If another profile owns the resource, dots keeps it and removes only your profile's ownership. Its configuration stays as it is until another apply changes it.
• If no owners remain, dots plans the resource's normal cleanup, including its removal safety checks.

Outputs work the same way. A shared output keeps its last applied value until a profile updates it or its last owner removes it.

Profiles can also control services:

if dots.profile == "work" then
  dots.systemd.start({ "example-vpn.service" })
end