sync and publish name the Rebase-Review Gate by its display name
The help and exit-42 cause texts still said "rebase-review gate" after the display name was settled; the generated reference and CONTRACT row follow. Files changed: - CHANGES.md - VERSION - docs/reference/commands/git.md - docs/reference/exit-codes.md - tools/CONTRACT.md - tools/chemenu/commands/git_publish.py Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
1 parent
e9f4759727
commit
5915b07383
6 files changed
+26
-25
No files matched your search
@@ -23,7 +23,7 @@ Fetch `<remote>/<branch>` and bring the local branch up to date with it.
|
||||
```text
|
||||
--remote <str> Git remote to reconcile against [default: origin]
|
||||
--branch <str> Branch to reconcile [default: main]
|
||||
--confirm-rebase TOKEN Clear the rebase-review gate for the exact upstream
|
||||
--confirm-rebase TOKEN Clear the Rebase-Review Gate for the exact upstream
|
||||
state and file overlap this token was issued for. The
|
||||
token comes from the gate's own refusal output.
|
||||
-h, --help Show this message and exit.
|
||||
@@ -38,7 +38,7 @@ tools/wikitool sync --confirm-rebase <token> # re-run after exit 42, once the
|
||||
|
||||
**Behaviour**
|
||||
|
||||
- Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases the local commits on top when both sides moved but touched disjoint files; exits 42 (rebase-review gate) when both sides touched the same file.
|
||||
- Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases the local commits on top when both sides moved but touched disjoint files; exits 42 (Rebase-Review Gate) when both sides touched the same file.
|
||||
- Files `wikitool` generates (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `kb/**/INDEX.md`) never count as an overlap and never reach the gate. Where they are what stops git - uncommitted ones in the way of a fast-forward or rebase, or a rebase conflict in them - they are merged mechanically: `kb/log.md` becomes the incoming log plus the entries only this side appended, and the catalog and `kb/provenance.md` are regenerated from the merged pages and left as an uncommitted change. A reconcile git can do on its own is unchanged and regenerates nothing.
|
||||
- Uncommitted changes that no incoming commit touches do not stop a rebase: they are carried through it (`git rebase --autostash`) and come back unchanged.
|
||||
- Before anything is set aside, the working tree is stored as a commit under `refs/wikitool/reconcile-backup`. A successful reconcile drops it; a failed one restores the working tree and names the ref.
|
||||
@@ -64,7 +64,7 @@ tools/wikitool sync --confirm-rebase <token> # re-run after exit 42, once the
|
||||
- `0` - The remote cannot be reached - reported and skipped, not a failure
|
||||
- `1` - The automatic rebase hit a real conflict outside the generated files (git failed), or `kb/log.md` was edited rather than appended to; it is aborted cleanly and the working tree restored
|
||||
- `1` - An uncommitted change - or an untracked file - sits on a path the incoming commits also change; nothing was changed
|
||||
- `42` - Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff
|
||||
- `42` - Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff
|
||||
|
||||
**See also**
|
||||
|
||||
@@ -91,7 +91,7 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
|
||||
gate's own refusal output - run without it first to
|
||||
see the file list, show that output to the user, and
|
||||
only pass this once they have approved it.
|
||||
--confirm-rebase TOKEN Clear the rebase-review gate raised by the pre-push
|
||||
--confirm-rebase TOKEN Clear the Rebase-Review Gate raised by the pre-push
|
||||
reconcile step. The token comes from that gate's own
|
||||
refusal output - see `tools/wikitool sync`.
|
||||
--threshold <int> Mass-Update Gate threshold: number of counted files
|
||||
@@ -117,7 +117,7 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
|
||||
|
||||
- Order: branch check and Publish-Remote Gate, then the reconcile with `<remote>/<branch>`, then the Mass-Update Gate, then `git add -A`, commit and push. `--no-push` skips all but the Mass-Update Gate and the commit.
|
||||
- Without `--no-push`, a remote that is not configured or cannot be reached ends the call with exit 1 at the reconcile - before the gate, `git add` and the commit, and also on a clean tree. Nothing is committed, the index and the working tree are unchanged, and the message names `--no-push` as the way to a local commit. The next `publish` that reaches the remote pushes that commit along with whatever is new. A remote that answers but has no `<branch>` yet (a new, empty repository) is not this case: the first publish of an instance commits and pushes as before.
|
||||
- Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, rebases the local commits on top when both sides moved but touched disjoint files, and exits 42 (rebase-review gate) when both sides touched the same file. A refused reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact upstream state and the set of files touched on both sides.
|
||||
- Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, rebases the local commits on top when both sides moved but touched disjoint files, and exits 42 (Rebase-Review Gate) when both sides touched the same file. A refused reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact upstream state and the set of files touched on both sides.
|
||||
- Generated files are never an overlap: where they are all that stops the reconcile, it merges them as `sync` does (both sides' log entries kept, the catalog and `kb/provenance.md` regenerated) and carries uncommitted changes no incoming commit touches through the rebase. The proactive reconcile runs before staging, so this publish commits the regenerated files - with `--path` too, see there; on the retry after a rejected push they get a commit of their own before the second push.
|
||||
- The push target must be the checked-out branch; this is checked before anything is staged. The unborn branch of a fresh `git init -b main` counts as checked out, so the first publish of a new instance works; a real detached HEAD is refused.
|
||||
- With nothing new to stage, a local commit the remote lacks is still pushed: one left behind by an earlier publish whose push failed, or every commit when the remote answers but does not have the branch yet (a new, empty remote repository).
|
||||
@@ -135,7 +135,7 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
|
||||
|
||||
- Changes files: yes
|
||||
- Idempotent: no
|
||||
- Atomic: No - sequential git operations. Every gate runs before staging, except on the one retry of a rejected push, where the rebase-review gate can exit 42 after the commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit
|
||||
- Atomic: No - sequential git operations. Every gate runs before staging, except on the one retry of a rejected push, where the Rebase-Review Gate can exit 42 after the commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit
|
||||
- Counts toward the session call budget: yes
|
||||
- Can reach the network: yes
|
||||
- Gates: mass-update, publish-remote, rebase-review - see [exit codes and gates](../exit-codes.md)
|
||||
@@ -149,7 +149,7 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
|
||||
- `1` - `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error
|
||||
- `1` - `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list
|
||||
- `42` - Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset
|
||||
- `42` - Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
|
||||
- `42` - Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
|
||||
- `42` - Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL
|
||||
|
||||
**See also**
|
||||
|
||||
Reference in new issue
Block a user