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 ```