From aa85c1d0b717a1ab831b3ae7a1f208bb771f4c19 Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sat, 5 Sep 2026 00:00:58 +0000 Subject: [PATCH] docs: correct the pages publish procedure `merge --ff-only main` cannot work: the histories diverged some time ago, so the step fails with `Not possible to fast-forward` and the publish stalls. Document the normal merge the branch's own history already uses, the stale local `pages` fast-forward that has to happen first, the take-main-wholesale conflict resolution, and the tree-equality check that is the real invariant. Co-Authored-By: Claude Opus 5 --- docs/operations-guide.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/operations-guide.md b/docs/operations-guide.md index 1ca2846..0162b53 100644 --- a/docs/operations-guide.md +++ b/docs/operations-guide.md @@ -117,7 +117,8 @@ Use a temporary worktree so the current checkout stays on `main`: ```bash git worktree add /tmp/ai-for-dummies-pages pages -git -C /tmp/ai-for-dummies-pages merge --ff-only main +git -C /tmp/ai-for-dummies-pages merge --ff-only origin/pages # local pages is often stale +git -C /tmp/ai-for-dummies-pages merge --no-edit main git -C /tmp/ai-for-dummies-pages push origin pages git worktree remove /tmp/ai-for-dummies-pages ``` @@ -125,6 +126,27 @@ git worktree remove /tmp/ai-for-dummies-pages The `pages` branch should represent the exact published source. Avoid editing it directly and avoid force-pushing it. +The two histories have diverged — `pages` carries merge commits and +cherry-picked duplicates of `main` commits — so `merge --ff-only main` fails +with `Not possible to fast-forward`. A normal merge is correct here, and +matches the `Merge branch 'main' into pages` commits already on the branch. +The invariant worth checking is the *tree*, not the history: + +```bash +git rev-parse main^{tree} pages^{tree} # must print the same hash twice +``` + +If the merge conflicts (duplicated commits touching the same lines will do +it), resolve by taking `main` wholesale, since `main` is the source of truth +for published content: + +```bash +git -C /tmp/ai-for-dummies-pages checkout main -- . +git -C /tmp/ai-for-dummies-pages add -A +git -C /tmp/ai-for-dummies-pages diff --cached main --stat # must be empty +git -C /tmp/ai-for-dummies-pages commit --no-edit +``` + ### 6. Verify the deployment ```bash @@ -491,7 +513,8 @@ git switch main git revert BAD_COMMIT git push origin main git worktree add /tmp/ai-for-dummies-pages pages -git -C /tmp/ai-for-dummies-pages merge --ff-only main +git -C /tmp/ai-for-dummies-pages merge --ff-only origin/pages # local pages is often stale +git -C /tmp/ai-for-dummies-pages merge --no-edit main git -C /tmp/ai-for-dummies-pages push origin pages git worktree remove /tmp/ai-for-dummies-pages ```