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 <noreply@anthropic.com>
This commit is contained in:
Marcos Paulo
2026-09-05 00:00:58 +00:00
parent e2bcfff5ab
commit aa85c1d0b7
+25 -2
View File
@@ -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
```