dotfiles

Dotfiles

Manages dotfiles, packages, and system state across multiple machines, with per-host and per-group overrides.

Quick start

curl https://git.capella.pro/capella/dotfiles/raw/master/start | bash -s -- sync

Or if already installed:

dotsync

Usage

start sync [--machine|--group <name>] [dot_file]
start list
start status
start packages [install|diff|save]

sync also commits and pushes the repo. It is unprivileged and fast; packages needs sudo, so it is deliberately not run as part of sync.

Repository layout

dots/                    # common dotfiles (all hosts)
dots.<hostname>/         # host-specific dotfiles
dots.@<group>/           # group-level dotfiles

to_sync[.<hostname>|.@<group>]    # which dotfiles to deploy
pkglist[.<hostname>|.@<group>]    # which packages to install
groups.<hostname>                 # group membership, one per line

start                    # this tool
bootstrap                # system state that needs root (see below)

Multi-host

Each host is identified by its hostname (uname -n).

File overrides

Resolution order (last wins): common -> groups (alphabetical) -> host.

A host copy of a file replaces the common one entirely, so host overrides must be complete files, not fragments.

Sync lists

to_sync                  # files synced to all hosts
to_sync.<hostname>       # additional files for a specific host
to_sync.@<group>         # additional files for a group

Groups

groups.<hostname>        # one group name per line

Example groups.jellyfish:

wayland

Hosts in the same group share to_sync.@<group>, dots.@<group>/ and pkglist.@<group>.

In-file markers

For files that are mostly shared with a few per-host differences, use markers instead of duplicating the whole file:

# @host jellyfish
set $mod Mod4
# @end

# @host tompot
set $mod Mod1
# @end

# @group wayland
exec waybar
# @end

• Lines between @host <name> and @end are included only on that host
• Lines between @group <name> and @end are included for hosts in that group
• Lines outside any markers are always included
• The comment prefix (#, //, ;, etc.) is auto-detected
• Files with markers are processed and written (not symlinked)
• Files without markers are symlinked as usual

Generated files carry a DO NOT EDIT header naming their source. Edit the file under dots/, not the copy in $HOME.

Adding dotfiles

# Add to common (all hosts):
dotsync sync .config/foo

# Add for this host only:
dotsync sync --machine .config/bar

# Add for a group:
dotsync sync --group wayland .config/baz

Packages

dotsync packages          # install tracked packages missing here
dotsync packages diff     # show drift both ways, change nothing
dotsync packages save     # write this host's packages to pkglist.<hostname>

Package lists are additive, not last-wins: pkglist, pkglist.@<group> and pkglist.<hostname> are unioned. A host list adds to the common one and can never remove from it. This is the opposite of how dotfiles resolve -- overriding makes sense for a config file, not for a package set.

Put a package in pkglist when you want it everywhere, and in pkglist.<hostname> only when it is genuinely specific to that machine (hardware, or a role the other hosts do not have).

Lists record explicitly installed packages only (yay -Qqe), so packages pulled in as dependencies stay out and get resolved automatically. Locally built -debug artifacts are filtered out: makepkg generates them on whichever machine did the build, and they are not installable elsewhere.

packages never removes anything. Dropping an entry from a list makes it show up under "installed but NOT tracked" in diff; uninstall it yourself. A sync command that can silently uninstall is not worth the convenience.

System state

bootstrap covers what dotsync cannot: things outside $HOME that need root.

./bootstrap

It is idempotent -- files are only written when their content differs, and units are skipped when already enabled, or when the package providing them is not installed on this host. Run it after dotsync packages.

Currently it manages:

• KillUserProcesses=no, as a logind drop-in so package upgrades cannot revert it (the default kills etterminal and takes the whole etserver down)
• greetd autologin into sway
• iwd stop timeout
• enabling the system and user units the desktop needs

It needs a real terminal, since sudo has to prompt. Host differences use a plain case $(uname -n), not @host markers -- those only apply to files deployed into $HOME.