heddle push

A normal push writes refs/heads/ and refs/notes/heddle. --all-threads writes every refs/heads/ and refs/tags/ as well, plus the notes ref. JSON output lists changed refs in refs_written, which you can check against git ls-remote .

push is one of the commands with a declared exit-code contract, and the distinction it draws is the one an agent most needs: 75 means the remote was unreachable and the same call is safe to retry; 76 means the remote rejected the payload and retrying unchanged will fail identically. Do not loop on 76. See Exit codes.

--dry-run previews the push plan — target, thread/track ref, the state that would be published, force status — without pushing, moving refs, capturing work, running hooks, or contacting the server for anything beyond read and plan.

Arguments

[REMOTE] string optional

Heddle remote name, native repository path, or hosted address.

[THREAD] string optional

Thread to push; alias for --thread.

Flags

--thread <thread>, -t <thread>

Thread to push.

--state <state>, -s <state>

State to push. default: HEAD

--force, -f

Force push.

--all-threads

Push every thread. In Git Overlay, also include every local Git tag.

--dry-run

Preview the push plan without pushing, moving refs, capturing work, running hooks, or contacting the server beyond read/plan.

--insecure

Allow cleartext (non-TLS) connections to non-loopback hosts. Prefer enabling TLS; use this only for intentional lab/VPN testing.

Exit codes

Declared by this command's contract, verbatim. Anything not listed contracts only to 0 on success and an unspecified non-zero on failure. The full table and the retry rule — in short, 75 is the only code that is safe to retry.

0

ok

75

remote unreachable; safe to retry

76

remote rejected payload; do not retry without changing inputs

78

no upstream configured

Examples

Publish the current thread

bash$ heddle push# exit 75 → retry the same call. exit 76 → change the inputs or escalate.

See also

• heddle pull
• heddle commit
• heddle land