From 768ebac44a3c417d13b2d1fd5cbd2ea559151c84 Mon Sep 17 00:00:00 2001 From: Stuart Meeks Date: Sun, 3 May 2026 14:13:10 +0000 Subject: [PATCH] docs: callout the one-time gotcha when adopting PreservePaths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A consumer hit it: switched their CLI from a pre-PreservePaths build to one configured with PreservePaths, expected the user's appsettings.Development.json to survive the upgrade, lost it. The cause is generic to self-updaters: the *first* upgrade onto the new version is performed by the *old* binary's update code, which doesn't know about PreservePaths and moves everything into .old/. From the next update onwards, preservation works as documented. Adds a short blockquote callout in the "Preserving user files" README section spelling this out, plus a hint to either ask users to back up state once or have the CLI bootstrap missing files on first launch after the upgrade. Docs-only — no version bump, no behaviour change. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 6228989..c7cd706 100644 --- a/README.md +++ b/README.md @@ -226,6 +226,19 @@ services.AddSelfUpdater(opts => }); ``` +> **One-time gotcha when adopting `PreservePaths`.** This option was +> introduced in v0.1.3. The first time a user upgrades *from* a +> pre-0.1.3 build of your CLI *to* a 0.1.3+ build, the swap is +> performed by the **old** binary's update code — which doesn't know +> about `PreservePaths` and will move every file (including the ones +> you intend to preserve) into `.old/`, where they're wiped on the +> next launch. From the *next* update onwards (a 0.1.3+ binary +> upgrading to a newer 0.1.3+ binary), preservation works as +> documented. If your users already have important state in the +> install directory before this change ships, document a one-shot +> manual backup step or have your CLI bootstrap missing files on +> first launch after the upgrade. + Patterns match the **top-level entry name** (the part before the first `/` in the pattern). `data/**` and `data/seed.json` both preserve the whole `data/` directory; nested-only preservation isn't supported in