dotfiles/README

# Dotfiles

Manages dotfiles across multiple machines via symlinks, 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

## Multi-host

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

### File overrides

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

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

### 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>` and `dots.@<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

## 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