Skip to content

docs: warn agents a slow git push is the pre-push hook, not a network hang #458

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zigrivers merged 1 commit into from
May 31, 2026
+26 −0
Merged

docs: warn agents a slow git push is the pre-push hook, not a network hang #458

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,21 @@ When modifying prompts:

See `docs/git-workflow.md` for the full workflow.

> **`git push` runs a multi-minute `pre-push` hook — a "hang" is usually the
> test suite, not the network.** `make hooks` installs a `pre-push` hook that
> runs the full bats/test suite (minutes) BEFORE the upload. A push that sits
> with no output is almost always the hook running tests, not a network/auth
> problem — do **not** kill it after a short wait, and do not start diagnosing
> HTTP/2, proxies, or credentials. Confirm with `GIT_TRACE=1 git push`: you'll
> see the receive-pack advertisement succeed, then
> `run_command: .git/hooks/pre-push …` followed by `1..N ok 1 …` bats output.
> (Note: this repo is public, so `git fetch`/`ls-remote` need no auth and return
> instantly — that contrast can make a slow push look network-specific when it
> isn't.) When you have **already run `make check-all` green on the exact commit
> being pushed**, the hook's run is redundant — use `git push --no-verify` to
> skip it and the upload completes in seconds. Otherwise, just let the hook
> finish (allow several minutes).

### Scaffold Release Workflow

The generic `/scaffold:release` command is for downstream projects. When
Expand Down
11 changes: 11 additions & 0 deletions docs/git-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,17 @@ Fallback: GitHub web UI (Settings > Branches > Add rule).

These are local-only. Each developer/agent runs `make hooks` after cloning.

> **Heads-up for AI agents: a slow `git push` is the pre-push hook, not a hung
> network.** The pre-push hook runs the full test suite (several minutes) before
> the upload, with little/no output. Do **not** interpret a quiet push as a
> network/auth/HTTP-2 failure and kill it early or start diagnosing connectivity
> — this repo is public, so `git fetch`/`ls-remote` need no auth and return
> instantly, which can make a slow push look network-specific when it's just the
> hook. Verify with `GIT_TRACE=1 git push` (you'll see `run_command:
> .git/hooks/pre-push …` then `1..N ok 1 …`). If you have **already run
> `make check-all` green on the exact commit**, skip the redundant run with
> `git push --no-verify`; otherwise let the hook finish.

### CI by Design

Quality gates run both locally (`make check-all`) and in CI. The CI workflow is the authoritative gate — local hooks are a convenience.
Expand Down
Loading