chemenu/docs/reference/commands/git.md

Git

Pulling in the remote and publishing a change - the only way a change leaves this checkout.

Contents

• sync
• publish

sync

Fetch <remote>/<branch> and bring the local branch up to date with it.

Synopsis

• wikitool sync [--remote origin] [--branch main] [--confirm-rebase TOKEN]

Options

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

Examples

tools/wikitool sync
tools/wikitool sync --confirm-rebase <token>    # re-run after exit 42, once the user approved

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.
• 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.
• A refused call performs no rebase attempt and leaves the branch where it was.
• The --confirm-rebase token covers the exact upstream state and the set of files touched on both sides, generated files excluded; either one moving makes it stale.
• Makes no commit, no push, and no forced operation of any kind.
• Three messages for a fetch that fails: no remote of that name, a remote that answers but has no such branch yet (a new, empty repository), and a remote that cannot be reached. All three exit 0 here; publish stops on the first and the last.
• Run it once at the start of a writing session.

Properties

• Changes files: yes
• Idempotent: yes
• Atomic: No - fetch, then at most one merge/rebase attempt, aborted cleanly on failure with the working tree restored; a success that merged generated files then rewrites the catalog
• Counts toward the session call budget: yes
• Can reach the network: yes
• Gates: rebase-review - see exit codes and gates

Exit codes

• 0 - success
• 0 - No remote configured - reported and skipped, not a failure
• 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

See also

• wikitool publish - runs the same reconcile before it commits and pushes
• instructions/session-setup.md - where a session runs sync
• instructions/gates.md - the gate procedure

publish

Reconcile with <remote>/<branch>, then stage all changes, commit, and push.

Synopsis

• wikitool publish --message "<op>: <desc>" [--no-push] [--confirm TOKEN] [--confirm-rebase TOKEN] [--threshold N] [--remote origin] [--branch main] [--path P ...]

Options

  --message <str>         Commit message summary, e.g. 'ingest: docker-
                          cheatsheet'  [required]
  --push / --no-push      [default: push]
  --confirm TOKEN         Clear the Mass-Update Gate for the exact changeset
                          this token was issued for. The token comes from the
                          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
                          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
                          at/above which clearance is required.  [default: 10]
  --remote <str>          Git remote to push to  [default: origin]
  --branch <str>          Branch to push  [default: main]
  --path <str>            Limit this publish to a path (repeatable). Lets a
                          large change be committed in reviewable batches
                          instead of one opaque commit - the Mass-Update Gate
                          then counts only the files in scope.
  -h, --help              Show this message and exit.

Examples

tools/wikitool publish --message "ingest: docker-cheatsheet"
tools/wikitool publish --confirm <token> --message "ingest: docker-cheatsheet"    # re-run after a Mass-Update exit 42, once the user approved
tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheatsheet"    # re-run after a rebase-review exit 42, once the user approved

Behaviour

• 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.
• 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).
• A rejected push that finds the remote unreachable on its one retry reports the original push error.
• A rejected push gets exactly one more reconcile-and-push; never more than one.
• Mass-Update Gate: counts the files that would be committed, refuses with exit 42 at --threshold (default 10) or more, and prints a review report - a scale line (file count, total lines added/removed, status breakdown), attention notes where they apply (deletions by name, control-plane and harness-config touches, published pages, the largest single change, binaries), and every counted path grouped by area with its status and churn. The list is what the commit will hold: it is computed from a scratch copy of the index after git add -A, so a path that is staged as deleted and back in the working tree is not counted twice, and a rename counts as its old path deleted plus its new path added. The real index and the working tree are not touched, so a refused publish leaves both byte-identical.
• Never counted and never shown for approval, but committed like everything else: anything under work/, and the files wikitool generates itself (kb/index.md, kb/log.md, kb/provenance.md, every INDEX.md under kb/). The refusal line accounts for both, by reason.
• The --confirm token covers each counted path, the blob id of its contents and the publish target: a different file list or edited contents need a new clearance.
• Publish-Remote Gate: when the checkout carries .wikitool-remotes.json and the push URL of --remote is not listed in it, exits 42 before the reconcile fetches anything. The URL is read with git remote get-url --push, so a repointed remote does not pass on its name. An absent file means unrestricted; a malformed one is an error, not permission.
• --path (repeatable) scopes the whole operation - gate count, staging and commit - to that subtree, with one exception: uncommitted generated files outside --path (kb/index.md, kb/log.md, kb/provenance.md, every INDEX.md under kb/) are staged and committed too, and a line names them - whether a reconcile or the change itself wrote them. They stay out of the gate count, and the --confirm token and the re-run line cover the --path given. Every other file outside --path is left as it is.
• Commit message: --message, then a Files changed: paragraph listing every committed path. When --message ends in a paragraph git reads as a trailer block (Co-Authored-By: and the like), that block stays the last paragraph and the list goes in front of it, since git reads trailers from the last paragraph only. git interpret-trailers decides whether there is such a block, and the list moves only when git reads the same trailers from the result; otherwise it is appended at the end. --message is not part of any gate token.
• After a successful commit or push whose changed files include tools/, types/, instructions/, AGENTS.md or a path ending in CONTRACT.md, prints one reminder line: the phase past this point (an issue-body rewrite, docs/ staleness, a changelog entry's accuracy) is not covered by docs verify, instructions verify or pytest. It is not a gate: no exit code change, nothing to clear, and silent for an ordinary content publish.

Properties

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

• 0 - success
• 1 - git failed - git add, git commit, git push, or the reconcile's automatic rebase (a conflict outside the generated files, an edited kb/log.md, or an uncommitted change on a path the incoming commits change)
• 1 - The push target (--branch) is not the checked-out branch, or HEAD is detached; the unborn branch of a fresh git init is not this case
• 1 - No --no-push, and the remote is not configured or cannot be reached; nothing was committed
• 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 - 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

• wikitool sync - the same reconcile on its own, without committing or pushing
• instructions/gates.md - the gate procedure
• instructions/setup-instance.md - the first publish of a new instance