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 # 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 hm 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 hm-linux-* or hm-darwin-* for you.
Every Homie command except hm init and hm selfupdate 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):
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 hm 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.
Adding a new distro # Distro support has three touch points. Grep for TODO(contrib) to see the current set:
