An Arch Linux and Windows config repository built on chezmoi, plus a uv-managed Python tool dotfiles for environment checks, post-reinstall recovery, daily backups and cache cleanup. Both platforms share one branch and one set of commands.
.chezmoiroot contains "home": chezmoi treats home/ as the source state
home/ dotfiles for both platforms (chezmoi source state)
.chezmoi.toml.tmpl generates the chezmoi config at init (encryption, key path, recipient)
.chezmoidata/platforms.toml platform ownership per target; .chezmoiignore derives from it
.chezmoiremove retired targets, deleted from every machine at apply
system/<distro>/ Linux /etc backup per distro, e.g. system/arch (separate chezmoi instance,
never deployed to ~)
packages/ package manifests: archpkg.txt / aptpkg.txt / scoopfile.json / winget.json
dotfiles.toml backup and cleanup lists and tunables (data; `dotfiles config` edits it)
src/dotfiles/ the Python tool (standard library only)
bootstrap.sh / .ps1 fresh-machine bootstrap: installs git, chezmoi, uv and clones the repo,
then hands over to dotfiles restore
docs/reference.md detailed reference: command behavior, encryption and platform rules,
cleanup targets, commit checks
docs/workflows.md branch roles and which path each kind of change takes
docs/architecture.md how the tool is organized, layering rules, where to extend it
docs/arch.md, kali.md, win.md per-machine notes for the three machines (Chinese)
Tool files at the repo top are not inside home/, so chezmoi apply never deploys them into the home directory.
-
chezmoi does the file work, the Python tool decides policy: every transfer between
~and the source state (attribute prefixes, encryption, template rendering, ignore rules) goes through chezmoi.dotfilesdecides which files to pass, whether to encrypt them and whether the result may be committed, then calls chezmoi to do it. The tool itself writes onlyplatforms.toml,dotfiles.toml(throughdotfiles config) and the manifests inpackages/. -
The source state is the backup list: whatever exists under
home/is managed, andbackupre-adds all of it. Thetrack/secretlists indotfiles.tomlonly discover new files (ignoresilences candidates you never want);platforms.tomlonly says on which platform each managed target deploys. -
Each command works in one direction:
backuponly copies~into the repo, andapply/restore/chezmoi applyonly copy the repo into~.backupnever deploys, never deletes from the source state (stop managing a target withchezmoi forgetand remove itsplatforms.tomlentry), never merges templates (it only reports their drift) and never pushes. -
Plain chezmoi stays first-class:
chezmoi add,re-addandeditproduce the same source files asbackup. Missing steps (an unregistered target, a sensitive file added in plaintext) are caught bydotfiles checkand the commit hooks, which enforce the rules whichever path made the change. -
Out of scope by design: externals such as
~/.config/nvim(separate git repos), the other platform's targets (invisible to chezmoi on this platform), and SSH private keys (regenerated per machine byrestore).
Prerequisites: the offline-stored age key file (AGE-SECRET-KEY-1…) and network access to GitHub.
If you need a proxy, set HTTPS_PROXY in the current terminal first.
curl -fsSLO https://raw.githubusercontent.com/virtualguard101/dotfiles/main/bootstrap.sh
less bootstrap.sh # read it before running
bash bootstrap.sh # shows the recovery plan only
bash bootstrap.sh --apply # execute (asks for the key file; or pass --key-file /path)In a regular (non-admin) PowerShell:
irm https://raw.githubusercontent.com/virtualguard101/dotfiles/main/bootstrap.ps1 -OutFile bootstrap.ps1
notepad bootstrap.ps1 # read it before running
powershell -NoProfile -ExecutionPolicy Bypass -File bootstrap.ps1 # plan only
powershell -NoProfile -ExecutionPolicy Bypass -File bootstrap.ps1 --apply # executeDo not pipe straight into curl … | bash or irm … | iex: stdin is then not a terminal and you cannot type the key path interactively.
bootstrap only installs git, chezmoi and uv (pacman on Arch, apt + pipx on Debian / Kali, winget on Windows; with --apply on Windows also scoop, after you confirm) and clones the public repo over HTTPS into ~/.local/share/chezmoi; everything else is done by
dotfiles restore:
| Step | What it does |
|---|---|
key |
writes the key to ~/.config/chezmoi/key.txt (owner-only permissions) and validates it against the repo's public key |
config |
generates the chezmoi config from home/.chezmoi.toml.tmpl |
dotfiles |
rehearses decryption once (nothing is written on failure), backs up files about to be overwritten or removed to ~/.local/state/dotfiles/pre-apply-*, then runs chezmoi apply |
system |
Linux: restores /etc from this distro's backup (system/<distro>/; skipped on a distro without one); hardware-bound files (fstab, crypttab, default/grub, ...) show diffs only; sudoers is validated with visudo first |
packages |
Arch: pacman installs packages from configured repos, AUR packages go to paru/yay; Debian / Kali: apt installs packages from the configured sources (skipped on other distros); Windows: winget import and scoop import |
externals |
fetches external repos such as the nvim config; temporarily connects directly when the git proxy is unreachable |
ssh |
generates any private key referenced by ~/.ssh/config that is missing (keys are never backed up), and can register the GitHub public key via gh |
shell |
Linux: sets the login shell to zsh |
hooks |
installs the commit-check hooks; repo and externals use HTTPS for fetch, push is switched to SSH |
verify |
chezmoi verify, the security check, and the permission audit |
Every step re-detects the current state before running; completed steps are skipped automatically.
Any failure stops the flow — fix the problem and rerun the same command to continue from that step.
Steps that install packages, modify /etc, change the shell or register keys ask for confirmation (--yes skips).
To run only some steps use --only, e.g. --only key,config,dotfiles; to skip some use --skip.
After recovery, the output lists items that need manual attention, usually: authorized_keys on your other servers (for the newly generated SSH keys) and the programs in packages/winget-unavailable.txt that are not in any winget source.
uv run dotfiles doctor # environment: toolchain, encryption config, repo and hooks, missing packages
uv run dotfiles backup -n # preview a backup
uv run dotfiles backup --commit # backup and commit (no push); then git push
uv run dotfiles apply # preview what deploying repo edits into ~ would change
uv run dotfiles apply --apply # deploy them (overwritten files are backed up first)
uv run dotfiles clean scan # see what caches can be cleaned
uv run dotfiles clean run --apply # clean the default tierWith just installed there are shortcuts: just doctor, just backup -n, just clean scan, etc.; see just --list.
| Command | What it does |
|---|---|
doctor [--json] |
environment detection (read-only); exit code 1 when a required condition is missing |
restore [--apply] [--only …] [--skip …] [--key-file path] [--yes] |
post-reinstall recovery; shows the plan by default |
apply [--apply] [TARGET…] |
deploy the repo into ~ (reverse of backup): diffs first, encrypted targets never shown decrypted |
status |
backup state: drift, unmanaged candidates, package manifests, permissions |
backup [-n] [--no-system] [--commit] |
re-add managed files -> add candidates -> /etc (Linux) -> package manifests -> security check |
check |
security check: plaintext secrets, .age format, must-encrypt targets, platform ownership |
audit [--apply] |
sensitive-file permissions (Linux 600/700, Windows ACL) |
system-restore [--apply] [/etc/path…] |
Linux: compare system/ with the current /etc and install as needed |
clean scan / list / run / leftovers |
cache cleanup; run previews by default, --apply executes |
config list / get / add / remove / set |
the lists and tunables in dotfiles.toml; edits keep comments |
Every modifying command previews by default. Full details in docs/reference.md.
-
The private key never enters the repo: only the public key is stored;
checkand the commit checks block any plaintext private key (AGE-SECRET-KEY-, PEM private key blocks) and any git-tracked key file. -
Sensitive files are always encrypted: at backup time the decision to encrypt is made by three layers — the manifest lists, the secret-pattern scan, and chezmoi's built-in scan. Commits are rejected when SSH configs, credential files,
sudoersetc. are not encrypted. Encrypted files deploy with 600 permissions. -
Double checks at commit and push: the pre-commit stage inspects the index; the pre-push stage inspects every commit about to be pushed (commits made with
--no-verifyare caught too). Output contains only file, line number and rule name — never the secret. -
Platform isolation: every target declares its owner in
platforms.toml; the other platform's targets (and their exclusive parent directories) are ignored, so a backup on one platform never overwrites the other platform's source files. -
Recovery never silently destroys existing files: decryption is rehearsed first, then files about to be overwritten or removed are backed up; hardware-bound
/etcfiles are never installed automatically. -
Transient plaintext only on tmpfs: staging for the
/etcbackup and restore lives in$XDG_RUNTIME_DIRand is deleted afterwards.