# Dotfiles Management

## Decision: YADM

Chosen for cross-platform dotfile management (macOS, Linux, Windows via WSL).

## Why YADM over alternatives

| Approach | Verdict |
|----------|---------|
| Git bare repo | No tooling for OS-specific configs |
| GNU Stow | No Windows support, symlinks can confuse tools |
| Chezmoi | Requires source dir + apply step, easy to forget |
| **YADM** | Files in place, just git, alternate files per OS |

### Key factors
- Works on Windows through WSL (native Windows not needed)
- Files stay in place, no copy/apply step
- Closest to "two-way sync" - just edit and commit
- Alternate files via naming convention: `.zshrc##os.Darwin`, `.zshrc##os.Linux`

## Setup

```bash
# Install
brew install yadm        # macOS
sudo pacman -S yadm      # Arch
# Windows: use through WSL

# Init new repo
yadm init
yadm remote add origin git@github.com:user/dotfiles.git

# Or clone existing
yadm clone git@github.com:user/dotfiles.git
```

## Workflow

```bash
# Edit files normally
vim ~/.zshrc

# Commit when ready
yadm add -u && yadm commit -m "updates" && yadm push

# Quick sync alias
alias yadm-sync='yadm add -u && yadm commit -m "sync $(date +%Y-%m-%d)" && yadm push'
```

## OS-Specific Files

Use alternate files with `##` suffix:

```
~/.zshrc##os.Darwin    # macOS
~/.zshrc##os.Linux     # Linux
~/.zshrc##default      # Fallback
```

YADM automatically uses the right one based on OS.

## Links

- https://yadm.io/
- https://github.com/yadm-dev/yadm

#dotfiles #yadm #git #linux #macos #configuration