.skel

✨ dotfiles (brew-first bootstrap)

Clean, straightforward dotfiles setup for Linux/WSL:

Supported OS: Ubuntu, Ubuntu (WSL), and macOS. Focus: A Homebrew-first, zsh-focused dotfiles toolkit.

• 🍺 Brew-first package install
• 🧾 Release verification (SHA256 + optional GPG on checksum)
• 🧩 Default skel profile deployment
• 🌃 Starship Tokyo Night preset by default
• 📝 Nano syntax highlighting via nanorc
• 🧱 tmux via Homebrew + oh-my-tmux base config
• 🤖 Optional inference tools (--install-inference: ollama + llmfit)
• 🧪 Dry-run support
• 🔎 Verbose debug mode when needed
• ♻️ Safe re-runs (preserves existing files by default)
• 🔒 Single-run lock to prevent concurrent installer collisions
• 📋 Optional machine-readable install report (--report-json)

🚀 Quick start (local)

chmod +x install.sh
# preview changes first
./install.sh --dry-run --verbose
# run install
./install.sh -y

By default, existing files like ~/.zshrc are kept as-is. Use --override only when you intentionally want to replace files. When --override modifies an existing config, a .bak.<date> backup is created.

🌐 Quick start (Pages bootstrap)

curl -fsSL https://dot.rly.wtf/bootstrap.sh | bash -s -- --tag v1.0.0

🗂️ Project layout

.
├── bootstrap.sh
├── install.sh
├── inventory/
│   └── default.yaml
├── packages/
│   └── packages.yaml
├── scripts/
│   ├── lib/brew-env.sh
│   ├── setup-pyenv.sh
│   ├── setup-starship.sh
│   └── post-install-checks.sh
├── test/
│   ├── check-no-root-config-duplicates.sh
│   ├── lib/test-shims.sh
│   ├── test-backup-collision.sh
│   ├── test-install-lock.sh
│   ├── test-installer-idempotency.sh
│   ├── test-oh-my-tmux.sh
│   ├── test-report-json.sh
│   ├── test-skel-merge-behavior.sh
│   ├── test-ssh-config-migration.sh
│   ├── test-inference-opt-in.sh
│   ├── test-nanorc-optional-failure.sh
│   ├── verify-release-reproducible.sh
│   └── installer.bats
└── skel/
    └── default/
        ├── .zshrc
        ├── .tmux.conf.local
        ├── .gitconfig
        ├── .ssh/config
        └── .config/starship.toml

📣 Output style

• Standard mode: concise stage updates + status emojis
• --verbose: extra 🔎 debug lines
• --dry-run: commands are printed with 🧪 and not executed
• Post-install checks use traffic lights (🟢 / 🟡 / 🔴)

⚙️ Installer flags

• --tag <tag>
• --host <host> (advanced optional profile name; most users can ignore this)
• --pyver <ver>
• --create-home-pyver
• --install-inference (use with -y for non-interactive runs)
• --dry-run
• --override (--force alias)
• --brew-only
• --no-apt
• --verbose
• --from-release (set internally by bootstrap)
• --report-json <path> (writes a JSON phase summary)
• --no-lock (advanced/debug; disables install lock guard)

🔐 Security env knobs

• BOOTSTRAP_GPG_FINGERPRINT to enforce expected checksum signer fingerprint in bootstrap.sh

📦 Build a release artifact manually

TAG=v1.0.0
REPO_NAME="$(basename "$PWD")"
mkdir -p dist
tar --sort=name --mtime='UTC 1970-01-01' --owner=0 --group=0 --numeric-owner \
  --exclude='.git' --exclude='./dist' -cf - . | gzip -n > "dist/${REPO_NAME}-${TAG}.tar.gz"
(cd dist && sha256sum "${REPO_NAME}-${TAG}.tar.gz" > "${REPO_NAME}-${TAG}.tar.gz.sha256")

Verify deterministic archive output:

./test/verify-release-reproducible.sh "$TAG"

On macOS, install GNU tar first for deterministic-archive verification: brew install gnu-tar

🧰 Package inventory workflow

packages/packages.yaml is the single source of truth for package lists (brew and apt_minimal sections). The default brew set includes core tools like tmux, ripgrep, fzf, and fd.

🤖 Agentic/Copilot standards

Repository AI guidance lives in .github/copilot-instructions.md and includes:

• DRY/minimal change expectations
• Idempotency and safe-default requirements
• Ample, purposeful section/function comments in shell scripts and tests

🧠 Migration notes

• Existing files in $HOME are preserved by default; --override is opt-in.
• Existing ~/.ssh/config is auto-migrated to ~/.ssh/config.local when local file is absent; managed ~/.ssh/config then includes ~/.ssh/config.local.

✅ CI tests

GitHub Actions runs a CI workflow that checks:

• shell syntax (bash -n)
• shellcheck linting
• no duplicate repo-root shell config files
• installer/bootstrap help output
• installer idempotency behavior (including preserving an existing .zshrc on reruns)
• backup collision handling for deterministic .bak.<date>[.<n>] naming
• skel directory merge behavior (preserve existing files, copy missing files)
• SSH config include migration behavior (test/test-ssh-config-migration.sh)
• oh-my-tmux bootstrap/preserve/override behavior (test/test-oh-my-tmux.sh)
• installer lock contention behavior (test/test-install-lock.sh)
• report JSON validity/escaping checks (test/test-report-json.sh)
• inference installer opt-in behavior (test/test-inference-opt-in.sh)
• optional nanorc clone failure handling (test/test-nanorc-optional-failure.sh)
• DRY BATS installer suite (test/installer.bats) running all integration checks
• release reproducibility verification (test/verify-release-reproducible.sh, tag workflow)

📝 Changelog

Release notes live in CHANGELOG.md.

📜 License

Released under UNLICENSE. See UNLICENSE.

This site is open source. Improve this page.