managing-homedir

---
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

1. Move the file into the repo at its `$HOME`-relative path (e.g. `~/.config/foo/bar` →
   `.config/foo/bar`).
2. Add the path to `manifest` — append ` macos` or ` linux` if it's OS-specific.
3. Run `homedir-manager install` (symlinks it; backs up the original).
4. 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

1. Clone your content repos into `~/git`. (Linux/headless: register an ssh key with GitHub if needed.)
2. Add `.homedir-manager.conf` to each repo if not already present (presence alone is enough).
3. Install the toolchain as needed (e.g. `mise`, `fnox`, `op`, `bw`, `jq`, `zsh`).
4. Run `homedir-manager install` to symlink everything into `$HOME`.
5. 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`.