From 95ea5b0aad7652396d4e5bd48b19f16542e56040 Mon Sep 17 00:00:00 2001 From: Bryan Lee <38807139+liby@users.noreply.github.com> Date: Fri, 11 Sep 2026 02:26:18 +0800 Subject: [PATCH 1/2] docs: explain cleanup when updating existing machines Document that removed source declarations can leave old files and shared configuration fields on existing machines. Require retirement commits to identify the affected non-secret targets or fields, explain their removal, and state which local content to preserve. Keep the existing policy without a historical deletion list while giving other Macs and downstream forks the information needed for cleanup. --- .github/README.md | 6 ++++++ .github/README_CN.md | 6 ++++++ AGENTS.md | 2 +- 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.github/README.md b/.github/README.md index 079eaef..ec78ca5 100644 --- a/.github/README.md +++ b/.github/README.md @@ -51,6 +51,12 @@ Editing encrypted files requires a YubiKey and should not be delegated to an age See chezmoi's [daily operations guide](https://www.chezmoi.io/user-guide/daily-operations/) for other commands. +## Updating existing machines + +Removing a file from source does not delete its existing copy in `$HOME`. Removing a field from a shared `modify_` configuration can also leave the old value in place. `chezmoi status` does not report files that are no longer managed. + +This repository does not keep a historical deletion list. Retirement commits describe the cleanup needed on existing machines. When updating a Mac or merging upstream into a fork, review changes since the version last applied on that machine and complete the cleanup there. Check the current contents before deleting a retired path or field; cleanup on one machine does not update the others. + ## Reuse Fork this repository and adapt it to your environment, or copy only the parts you need. Before applying the full setup, review and adjust `.chezmoi.toml.tmpl`, `Brewfile`, and `.chezmoiscripts/`. diff --git a/.github/README_CN.md b/.github/README_CN.md index e32c7f2..e88842f 100644 --- a/.github/README_CN.md +++ b/.github/README_CN.md @@ -51,6 +51,12 @@ chezmoi edit-encrypted # 编辑未由 chezmoi 管理的加密文件 其他命令参见 [chezmoi 日常操作指南](https://www.chezmoi.io/user-guide/daily-operations/)。 +## 更新已有配置的机器 + +从 source 删除文件，不会删除 `$HOME` 中已有的副本。从共享的 `modify_` 配置中删除字段，也可能保留旧值。`chezmoi status` 不会报告已经退出管理的文件。 + +本仓库不维护历史删除清单。涉及退役的提交会说明已有机器需要完成的清理。更新 Mac 或向 fork 合并上游变更时，请检查这台机器上次应用版本之后的变更，并在该机器上完成清理。删除旧路径或字段前，先核对当前内容；一台机器上的清理不会同步到其他机器。 + ## 取用 可以 Fork 本仓库并根据自己的环境调整，也可以只取用需要的部分。若要应用整套配置，请先检查并调整 `.chezmoi.toml.tmpl`、`Brewfile` 和 `.chezmoiscripts/`。 diff --git a/AGENTS.md b/AGENTS.md index 687118a..9e66c06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Dotfiles managed by [chezmoi](https://www.chezmoi.io/) from `~/.local/share/chez - Before committing, run `chezmoi status --exclude=encrypted ` and `chezmoi diff ` for each changed non-secret managed target in scope; never run bare `chezmoi status` or `chezmoi diff`, which can generate decrypted target content. Reserve repository-wide status checks for requested drift audits, and report inaccessible targets as gaps in those audits without widening permissions. Read `-` as destination-only and `+` as rendered-target-only. Re-add destination-only drift only when it belongs to the requested change; report unrelated drift without modifying it. When both destination and target changed, show the scoped diff. - Use `chezmoi merge ` only for an explicitly selected non-secret, non-`modify_` target; a templated target requires manual review to preserve template directives. - Fold a follow-up change to the same logical unit into its existing unpushed commit (`git commit --amend` or fixup) instead of appending a commit per request; append-only committing turns one feature into a chain that later needs a history rewrite. Start a new commit only for a separate concern, a pushed base, or another author's commit. -- When retiring or replacing a managed path, verify the exact non-secret destination, then delete the obsolete source and the existing live destination in the same change. Never add `remove_` entries, compatibility readers, or other migration markers; handle any later residue through an explicit audit. +- When retiring or replacing a managed path, verify the exact non-secret destination, then delete the obsolete source and the existing live destination in the same change. Never add `remove_` entries, compatibility readers, or other migration markers; handle any later residue through an explicit audit. In retirement commits, identify the non-secret target paths or fields, the reason for removal, and any local content that must be preserved so other machines can complete the cleanup. - For agent skill changes, run `ruby dot_agents/skills/scripts/validate-skills.rb --smoke`. Keep `CLI_SMOKE_COMMANDS` in sync only for skills whose instructions depend on current CLI behavior. - Preserve order where it affects behavior, including workflow steps, hook lists, and script prefixes. When choosing a layout for unordered configuration keys, prefer an established upstream order from the schema, examples, or generated output; otherwise use alphabetical order for small or unrelated sets and functional groups when they aid navigation. Do not reorder an existing file merely to match another one. - In Markdown source, never hard-wrap prose to a fixed column. Keep each prose paragraph, including the prose portion of a list item or blockquote, on one physical line; when content needs intentional separation, create an explicit Markdown block instead of a soft line break. Preserve separate lines for headings, blank paragraph boundaries, separate list items, table rows, fenced code, and explicit hard breaks ending in two spaces or a backslash. From a21ea06e900703a693e0527418ea5c85a3c54773 Mon Sep 17 00:00:00 2001 From: Bryan Lee <38807139+liby@users.noreply.github.com> Date: Fri, 11 Sep 2026 02:51:51 +0800 Subject: [PATCH 2/2] docs: separate upgrade steps from retirement rationale Keep per-machine cleanup steps in the READMEs and explain source deletion behavior and the cost of avoiding deletion history under configuration ownership. Keep the retirement commit requirements in the contributor workflow so downstream users can find cleanup details in the history. --- .github/CONCEPTS.md | 2 ++ .github/README.md | 4 +--- .github/README_CN.md | 4 +--- AGENTS.md | 2 +- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/.github/CONCEPTS.md b/.github/CONCEPTS.md index a5bb8b3..f191c92 100644 --- a/.github/CONCEPTS.md +++ b/.github/CONCEPTS.md @@ -48,6 +48,8 @@ Not every configuration is fully replaced. Applications such as Codex and Claude Replace subtrees that source fully owns so that removed fields disappear from the destination. For shared subtrees, preserve application-owned fields through an overlay or explicit exceptions during replacement. Establish ownership from the application's writers rather than the shape of the configuration. An overlay preserves undeclared fields; removing a source declaration does not by itself retire its destination state. +Deleting a source file likewise leaves its existing destination in place, and `chezmoi status` no longer reports that unmanaged path. The repository avoids persistent deletion lists and migration markers so source describes the current configuration without accumulating past removals. The trade-off is that existing machines need explicit cleanup; `.chezmoiremove` would automate file deletion but not cleanup of fields in shared configurations. + The JSON and TOML modifiers compare parsed values before serializing, so reordering object keys in their fragments alone leaves the destination unchanged. Fragments embedded in scripts, such as [`codex/requirements.toml`](../.chezmoitemplates/codex/requirements.toml), also affect script trigger hashes; their ordering changes can rerun the consuming script. Chezmoi source manages portable, durable preferences, including established interaction habits, when they should remain consistent across machines. It leaves matching convenience defaults implicit unless an explicit value enforces a repository boundary or counters observed write-back drift. Generated runtime state, machine-specific paths, and settings synchronized elsewhere remain owned by their existing systems. diff --git a/.github/README.md b/.github/README.md index ec78ca5..30a83b6 100644 --- a/.github/README.md +++ b/.github/README.md @@ -53,9 +53,7 @@ See chezmoi's [daily operations guide](https://www.chezmoi.io/user-guide/daily-o ## Updating existing machines -Removing a file from source does not delete its existing copy in `$HOME`. Removing a field from a shared `modify_` configuration can also leave the old value in place. `chezmoi status` does not report files that are no longer managed. - -This repository does not keep a historical deletion list. Retirement commits describe the cleanup needed on existing machines. When updating a Mac or merging upstream into a fork, review changes since the version last applied on that machine and complete the cleanup there. Check the current contents before deleting a retired path or field; cleanup on one machine does not update the others. +When updating an existing Mac or merging upstream into a fork, review commits since the version last applied on that machine for retired paths and fields. Check their current contents before removing them, keeping any local changes you still need. Applying the new source [does not clean up all retired configuration](CONCEPTS.md#configuration-ownership), even when `chezmoi status` is empty. ## Reuse diff --git a/.github/README_CN.md b/.github/README_CN.md index e88842f..dbb0473 100644 --- a/.github/README_CN.md +++ b/.github/README_CN.md @@ -53,9 +53,7 @@ chezmoi edit-encrypted # 编辑未由 chezmoi 管理的加密文件 ## 更新已有配置的机器 -从 source 删除文件，不会删除 `$HOME` 中已有的副本。从共享的 `modify_` 配置中删除字段，也可能保留旧值。`chezmoi status` 不会报告已经退出管理的文件。 - -本仓库不维护历史删除清单。涉及退役的提交会说明已有机器需要完成的清理。更新 Mac 或向 fork 合并上游变更时，请检查这台机器上次应用版本之后的变更，并在该机器上完成清理。删除旧路径或字段前，先核对当前内容；一台机器上的清理不会同步到其他机器。 +更新已有的 Mac 或向 fork 合并上游变更时，请检查这台机器上次应用版本之后的提交，确认哪些路径和字段需要清理。删除前先核对当前内容，保留仍然需要的本地修改。应用新版本[不会清理所有已退役的配置](CONCEPTS.md#configuration-ownership)，即使 `chezmoi status` 没有输出。 ## 取用 diff --git a/AGENTS.md b/AGENTS.md index 9e66c06..b31d2d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Dotfiles managed by [chezmoi](https://www.chezmoi.io/) from `~/.local/share/chez - Before committing, run `chezmoi status --exclude=encrypted ` and `chezmoi diff ` for each changed non-secret managed target in scope; never run bare `chezmoi status` or `chezmoi diff`, which can generate decrypted target content. Reserve repository-wide status checks for requested drift audits, and report inaccessible targets as gaps in those audits without widening permissions. Read `-` as destination-only and `+` as rendered-target-only. Re-add destination-only drift only when it belongs to the requested change; report unrelated drift without modifying it. When both destination and target changed, show the scoped diff. - Use `chezmoi merge ` only for an explicitly selected non-secret, non-`modify_` target; a templated target requires manual review to preserve template directives. - Fold a follow-up change to the same logical unit into its existing unpushed commit (`git commit --amend` or fixup) instead of appending a commit per request; append-only committing turns one feature into a chain that later needs a history rewrite. Start a new commit only for a separate concern, a pushed base, or another author's commit. -- When retiring or replacing a managed path, verify the exact non-secret destination, then delete the obsolete source and the existing live destination in the same change. Never add `remove_` entries, compatibility readers, or other migration markers; handle any later residue through an explicit audit. In retirement commits, identify the non-secret target paths or fields, the reason for removal, and any local content that must be preserved so other machines can complete the cleanup. +- When retiring or replacing a managed path, verify the exact non-secret destination, then delete the obsolete source and the existing live destination in the same change. Never add `remove_` entries, compatibility readers, or other migration markers; handle any later residue through an explicit audit. In retirement commits, name the affected non-secret target paths or fields, explain why they were removed, and note any local content to preserve. - For agent skill changes, run `ruby dot_agents/skills/scripts/validate-skills.rb --smoke`. Keep `CLI_SMOKE_COMMANDS` in sync only for skills whose instructions depend on current CLI behavior. - Preserve order where it affects behavior, including workflow steps, hook lists, and script prefixes. When choosing a layout for unordered configuration keys, prefer an established upstream order from the schema, examples, or generated output; otherwise use alphabetical order for small or unrelated sets and functional groups when they aid navigation. Do not reorder an existing file merely to match another one. - In Markdown source, never hard-wrap prose to a fixed column. Keep each prose paragraph, including the prose portion of a list item or blockquote, on one physical line; when content needs intentional separation, create an explicit Markdown block instead of a soft line break. Preserve separate lines for headings, blank paragraph boundaries, separate list items, table rows, fenced code, and explicit hard breaks ending in two spaces or a backslash.