chezmoi-migration

Applies changelog-recorded destructive chezmoi migrations per machine with idempotent verification.

Updated Jan 19, 2023
One-click install
npx skills add https://github.com/inkfin/dotfiles --skill chezmoi-migration-inkfin
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: chezmoi-migration
Source: https://github.com/inkfin/dotfiles/tree/main/.agents/skills/chezmoi-migration
Command: npx skills add https://github.com/inkfin/dotfiles --skill chezmoi-migration-inkfin

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Breaking changes in a chezmoi-managed dotfiles repository often leave old machines needing manual cleanup after chezmoi apply, such as deleting moved files or migrating local config. This Skill applies those destructive migrations from changelog entries on request, so every machine converges safely without tracking applied state in the shared repo. ## Core Features & Use Cases - Residual-test gating: Determines whether a change needs a changelog entry by checking if old machines still require hand work after apply. - Condition-driven filtering: Runs each entry's completion condition on the current machine instead of trusting shared state, since the changelog is shared across all machines. - Idempotent application with safety rules: Executes migration steps exactly as written, reads files before deleting, and stops on partial failure. - Use Case: After restructuring your Neovim config paths in chezmoi, say "更新一下" on each machine to apply the recorded migration, verify completion conditions, and write a machine-local marker. ## Quick Start Ask the assistant to update the config by applying all pending chezmoi migration entries from the changelogs directory on this machine.

Frequently Asked Questions about chezmoi-migration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I apply pending chezmoi migrations on a new machine?

List changelog entries matching the date prefix, run each entry's completion condition to filter pending ones, then execute the migration steps in date order. Afterward verify each condition holds and write a marker under ~/.local/state/chezmoi-migrations/.

When does a chezmoi change need a changelog migration entry?

A change needs an entry when it fails the residual test: after chezmoi apply, an old machine still needs hand work such as deleting moved files, migrating local config, or adjusting per-environment paths. Purely additive changes need no entry.

Can I re-run a chezmoi migration entry that was already applied?

Yes, every migration entry is idempotent, so re-running a satisfied entry is a no-op. The completion condition is the authoritative gate, and the machine-local marker file is bookkeeping only.

Why should applied migration state not be stored in the chezmoi repo?

The changelog file is shared by every machine, so any applied flag in it cannot reflect whether a specific machine is done and would go stale. Machine-local markers under ~/.local/state/chezmoi-migrations/ track per-machine progress instead.

What safety checks run before destructive chezmoi migration steps?

Read current files before deleting anything, back up when unsure, keep secrets out of the source tree, and confirm scope when an entry touches more than requested. If a step fails, stop and report the partial state rather than forcing through.