From 511b879c40110cfa135fb02c4532ba18161d918e Mon Sep 17 00:00:00 2001 From: brooklyn! Date: Thu, 24 Sep 2026 02:02:52 -0500 Subject: [PATCH] docs(update): document rescue refs for local commits on the target branch --- website/docs/getting-started/updating.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/docs/getting-started/updating.md b/website/docs/getting-started/updating.md index 33bd442441..0c8bb43e87 100644 --- a/website/docs/getting-started/updating.md +++ b/website/docs/getting-started/updating.md @@ -88,6 +88,10 @@ If you *deliberately* run a custom branch (local patches maintained on top of ma When the parked branch has **uncommitted changes** (dirty tree), Hermes does **not** touch it. The code update is marked **SKIPPED** with a loud warning naming the branch, how far behind `origin/main` it is, and the exact commands to resolve — instead of pretending the update succeeded. The completion line always shows the actual branch and HEAD (`✓ Update complete! [main @ 30fcf9580]`) so drift is visible at a glance. Set `updates.auto_switch_parked_branch: false` in `config.yaml` to disable the auto-switch entirely (the skip warning still fires). +### Local commits on the target branch + +Commits made directly on the update target (`main`) stop fast-forwards once upstream moves, and the checkout cannot tell them apart from an upstream force-push, so the update resets `main` to `origin/main`. Before the reset it saves the old HEAD as `refs/hermes-update-backups/diverged-main--` and prints that ref along with how many commits leave the branch. `git log origin/main..` lists them; `git branch ` or `git cherry-pick` brings them back. Re-running the installer over an existing checkout (`install.sh` / `install.ps1`, which desktop bootstrap does) writes the same refs. Whenever `hermes update` writes one, it keeps the ten newest per kind and drops any older than 30 days. To carry patches across updates, keep them on a custom branch with `updates.parked_branch_strategy: update_in_place` instead. + ### Local changes on non-interactive updates When you run `hermes update` in a terminal, Hermes stashes any uncommitted source-tree changes, pulls, then **asks** whether to restore them — exactly as it always has. Nothing changes for interactive updates.