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 homie # One static binary, no runtime, no dependencies:
curl -fsSL https://homie.sh/install.sh | bash Prefer not to pipe a script? See Install for manual download, version pinning, and building from source.
The fastest path is the install script, but Homie is a single static binary — there’s nothing stopping you from grabbing it any way you like.
Install script (recommended) # Detects your OS (Linux or macOS) and arch, downloads the matching release, verifies its SHA256, and drops homie into /usr/local/bin (or ~/.local/bin if you’re not root):
curl -fsSL https://homie.sh/install.sh | bash The same one-liner works on Linux and macOS (Apple Silicon and Intel) — the script picks homie-linux-* or homie-darwin-* for you.
Every Homie command except homie init and homie selfupdate expects to be run from the root of a user environment repo, or with HOMIE_REPO set to its path.
homie init # Interactively scaffolds a brand new user environment repo. Run this once on the first machine. Subsequent machines clone the result via bootstrap.sh.
homie init ~/dotfiles You can also pass flags non-interactively (useful in CI):
homie.toml lives at the root of your user environment repo. It is the only configuration Homie reads. Everything else — your home/ tree and scripts/ — is on disk, where you can see and version it.
Minimal valid file:
[user] name = "Scout Homes" email = "scout@homie.sh" That’s it. Every other table is optional. The sections below describe each one in order.
[user] # Identity. Both fields are required.
Everything Homie writes into $HOME comes from one directory in your repo: home/. The shape of the file decides what happens to it:
A plain file (home/.zshrc) becomes a symlink in $HOME at the matching path (~/.zshrc). A file whose name ends in .tmpl (home/.gitconfig.tmpl) is rendered through Go text/template + Sprig, with the .tmpl suffix stripped on the way out (~/.gitconfig). That’s it. The suffix is the only disambiguator. Two trees writing the same target are resolved by tag specificity, not by configuration.
The honest version of the matrix on the homepage. Each of these tools is good at what it’s designed for. Pick Homie when the tradeoffs below match how you actually work.
Homie covers Linux and macOS from one tool and one repo, so the same dotfiles, templates, and provisioning work across both. That’s worth keeping in mind below: on macOS you might otherwise reach for brew bundle (packages only — no dotfiles, templating, or multi-host overlays) or Nix / Home Manager (more powerful, but heavier).
Working examples for the setups that come up most. Each recipe shows just the relevant slice of homie.toml and the files you’d add — drop into a homie init-scaffolded repo and adapt.
Work laptop, personal laptop, same repo # The classic “one repo, different identity per machine” pattern. Use the [profile] to mark the machine, and [vars] to carry the work-only email so it never lands in your personal commits.
Short answers to the questions that come up most. For the long version of the tool comparisons, see Compare.
Why TOML? # Because it’s structured enough to validate, simple enough to hand-edit, and free of YAML’s foot-guns (significant whitespace, no parsing as false, sexagesimal numbers, the Norway problem). It’s also what chezmoi uses, so anyone arriving from there has zero ramp-up.
Homie is small on purpose, but the surface that needs to grow first is distro and package-manager coverage. The code is structured so adding a new one is a focused change in two or three files.
Source lives at github.com/kurowski/homie. PRs welcome; the rest of this page walks through the common paths.
Learning the codebase with a tutor # The repository carries a Rolling Start map in .rolling/, so Claude Code can teach you the code from it: a lesson at a time, each with an exercise on your own checkout, reviewed like a pull request. It covers the command layer, config and the home tree, the package backends, scripts, and the scaffold. You need Go and git; nothing else runs. Open Claude Code in your clone and trust the folder: the repository’s settings add the tutor’s plugin. Then:
