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:
@@ -117,7 +117,8 @@ Use a temporary worktree so the current checkout stays on `main`:
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
git worktree add /tmp/ai-for-dummies-pages pages
|
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 -C /tmp/ai-for-dummies-pages push origin pages
|
||||||
git worktree remove /tmp/ai-for-dummies-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
|
The `pages` branch should represent the exact published source. Avoid editing
|
||||||
it directly and avoid force-pushing it.
|
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
|
### 6. Verify the deployment
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
@@ -491,7 +513,8 @@ git switch main
|
|||||||
git revert BAD_COMMIT
|
git revert BAD_COMMIT
|
||||||
git push origin main
|
git push origin main
|
||||||
git worktree add /tmp/ai-for-dummies-pages pages
|
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 -C /tmp/ai-for-dummies-pages push origin pages
|
||||||
git worktree remove /tmp/ai-for-dummies-pages
|
git worktree remove /tmp/ai-for-dummies-pages
|
||||||
```
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user