| name | managing-homedir |
| description | Use when adding, changing, deploying, onboarding, or auditing homedir-manager content repos — the marker-based symlink deployment system that manages dotfiles and config across your machines. Covers the update workflow, the manifest, OS-splitting, secrets, new-machine onboarding, and the audit process. |
Managing homedir-manager content repos
One or more content repos, each opting in with a .homedir-manager.conf marker file. The engine
discovers every immediate subdirectory of ~/git (override with $HOMEDIR_MANAGER_BASE) that
contains this marker and treats it as a managed repo.
Each repo has a manifest (<repo-relative path> [macos|linux]) and homedir-manager install
symlinks each entry into $HOME, backing up anything it replaces to ~/.dotfiles-backup/<ts>/.
Updating (the common case)
Files in $HOME are symlinks into the repo, so edit in place, then git commit. That's it —
the change is already live. You only run homedir-manager install after adding a new manifest
entry or on a new machine. Commit + push, then git pull on the other hosts.
Adding a new config
- Move the file into the repo at its
$HOME-relative path (e.g. ~/.config/foo/bar →
.config/foo/bar).
- Add the path to
manifest — append macos or linux if it's OS-specific.
- Run
homedir-manager install (symlinks it; backs up the original).
- Commit.
$HOME-ize any absolute paths inside the file so it's portable.
OS-specific config
Prefer separate files chosen by the manifest tag (.config/zsh/macos.zsh vs linux.zsh,
.ssh/config.d/macos.conf) over in-file uname branches. The common file sources the OS file only
if present, so it's a no-op on the other OS. Guard tool integrations with command -v.
Secrets
Never commit a value. Tools get secrets lazily via fnox (share/SECRETS.md): op (1Password,
work) + bw (Bitwarden, personal), with Bitwarden unlocked silently from 1Password via bw-unlock.
Headless machines (no 1Password app) use a service-account token in ~/.config/op/env (600,
untracked) — see SECRETS.md "Headless / unattended machines". When handling a secret value in the
shell, only ever pipe it to wc -c or shasum — never echo it, never 2>&1/-v/--full.
Onboarding a new machine
- Clone your content repos into
~/git. (Linux/headless: register an ssh key with GitHub if needed.)
- Add
.homedir-manager.conf to each repo if not already present (presence alone is enough).
- Install the toolchain as needed (e.g.
mise, fnox, op, bw, jq, zsh).
- Run
homedir-manager install to symlink everything into $HOME.
- Headless secrets: mint a per-box 1Password service account, drop the token in
~/.config/op/env
(route it only through a temp file / $(cat …), never echo), then verify the chain.
Claude config (.claude/)
CLAUDE.md, commands/, and standalone skills under .claude/skills/ can be versioned via
individual manifest entries and symlinked into ~/.claude/. This keeps host-specific
project-linked skills (a ~/.claude/skills/<x> that symlinks into a project repo) untouched. To
version a new standalone skill: drop it in .claude/skills/<name>/, add a manifest line, run
homedir-manager install.
Auditing
Run homedir-manager audit before pushing and periodically (leak scan + deploy drift + perms). Full
process and the by-eye checks are in share/AUDITING.md.
