Documentation

The reference for getting Homie installed, configured, and onto every machine you live in.

Start with the quick start if you’ve never used Homie before. If you’re coming from chezmoi, Ansible, Stow, or Nix, the comparison is a faster orientation.

Contributing

Coming soon — how to add a new distro (// TODO(contrib) markers in source point at the gaps), how to add a package manager, how to run the e2e harness locally, and the contribution process.

FAQ

Coming soon — quick answers to “Why TOML?”, “Why symlinks?”, “Is this Nix?”, “How does it differ from chezmoi?”, and other questions that come up often.

Recipes

Coming soon — concrete patterns: work-laptop with tagged secrets, dotfiles + system fonts on Fedora, devcontainer setup, GitHub Codespaces, shared-server (no root) installs, and more.

Compare

Coming soon — the detailed comparison expanding on the matrix from the homepage. Honest take on where each tool wins and where Homie fits.

Templates

Coming soon — template syntax reference, the full Sprig function list, the hasTag helper, and a cookbook of common patterns (per-profile blocks, OS-conditional config, defaults).

homie.toml

Coming soon — full reference for every table and field in homie.toml, with per-distro override examples and the defaults hm init writes.

Every Homie command except hm init expects to be run from the root of a user environment repo, or with HM_REPO set to its path. hm init # Interactively scaffolds a brand new user environment repo. Run this once on the first machine. Subsequent machines clone the result via bootstrap.sh. hm init ~/dotfiles You can also pass flags non-interactively (useful in CI):

Quick start

This walks through scaffolding a fresh Homie repo, putting your first dotfile under management, and bootstrapping the same environment on a second machine. About five minutes if you already have git + GitHub set up. 1. Install hm # Grab the latest static binary from Releases. One file, no runtime, no dependencies. ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') curl -fsSL -o /tmp/hm \ "https://github.com/kurowski/homie/releases/latest/download/hm-linux-${ARCH}" chmod +x /tmp/hm sudo mv /tmp/hm /usr/local/bin/hm hm --version 2. Scaffold a user environment repo # hm init writes a starter repo — homie.toml, a bootstrap.sh, an example dotfile, an example template, and a sample script — that’s yours to grow into.