Quick start

This is the shortest path to a working setup.

1) Initialize

hometree init

If you haven't installed hometree yet, see docs/install.md.

This creates:

• A config file at ~/.config/hometree/config.toml (XDG-aware)
• A bare repo at ~/.local/share/hometree/repo.git

2) Track files

hometree track ~/.config/myapp/config.toml

track adds paths to the managed set if they are under managed roots or you pass --allow-outside.

3) Stage and snapshot

hometree snapshot -m "track config"

Snapshots are git commits created from staged changes.

4) Verify

hometree verify --strict

Use --with-secrets to control secrets verification:

hometree verify --with-secrets=presence
hometree verify --with-secrets=decrypt --show-paths

5) Deploy and rollback (optional)

Preview first:

hometree plan deploy HEAD

Deploy a commit:

hometree deploy HEAD

Rollback one generation:

hometree rollback --steps 1

6) Connect to GitHub (optional)

Add a remote and push your dotfiles:

hometree remote add origin [email protected]:YOUR_USER/dotfiles.git
hometree remote push -u origin -b main

Check configured remotes:

hometree remote list

For subsequent pushes:

hometree remote push

Setup on a new machine

If you already have dotfiles in a remote repo, setup is a single command:

hometree init --from [email protected]:YOUR_USER/dotfiles.git --deploy

This clones the repo, extracts your config, and deploys all files to $HOME.

Or step by step:

hometree init --from [email protected]:YOUR_USER/dotfiles.git
hometree plan deploy HEAD   # preview changes
hometree deploy HEAD        # apply

7) Encrypt secrets with age (optional)

hometree uses age encryption to keep sensitive files out of git history.

Generate an age keypair:

age-keygen -o ~/.config/hometree/keys/identity.txt

Copy the public key from the output (starts with age1...) and add it to ~/.config/hometree/config.toml:

[secrets]
enabled = true
backend = "age"
recipients = ["age1your-public-key-here"]
identity_files = ["~/.config/hometree/keys/identity.txt"]

Add a secret file:

hometree secret add ~/.config/app/secret.txt
hometree snapshot -m "add encrypted secret"

The plaintext stays local; only the .age ciphertext is committed.

Common next steps

• Edit docs/config.md to customize managed roots or ignore patterns.
• Enable the daemon if you want event-driven staging: docs/daemon.md.
• See full secrets reference: docs/secrets.md.