↓ Skip to main content
Homie
Homie
  1. Documentation/

Quick start

Table of Contents

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.

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.

hm init ~/dotfiles

It’ll ask for your name, email, and GitHub username so it can wire up bootstrap.sh with the right clone URL.

3. Push it to GitHub
#

Create an empty repo at github.com/<you>/dotfiles (or whatever you named it during hm init), then:

cd ~/dotfiles
git init -b main
git add -A
git commit -m "initial scaffold"
git remote add origin git@github.com:<you>/dotfiles.git
git push -u origin main

4. Apply on the machine you’re on
#

Reconcile your $HOME with the scaffolded repo:

hm apply

You’ll see Charm-styled progress as Homie installs the listed packages, symlinks your dotfiles, renders your templates, and runs your scripts.

5. Bootstrap on a fresh machine
#

On any other Linux or macOS box — bare metal, VM, container, Codespace — run:

curl https://raw.githubusercontent.com/<you>/dotfiles/main/bootstrap.sh | bash

That downloads the right hm binary for the OS and CPU, clones your repo, and runs hm apply. Done.

bootstrap.sh makes sure git is present first. On Linux it also installs ca-certificates if needed. On macOS git comes from the Xcode Command Line Tools (xcode-select --install), and Homebrew is not required — install it only if you declare [packages].

Where to next?
#

  • Commands — every hm subcommand explained.
  • homie.toml — full config reference.
  • Dotfiles — symlinks, templates, tag-gated trees, overrides.
  • Recipes — concrete patterns for common setups.