push

name	push
description	Use when running git push or diagnosing why a push failed. Especially when output mixes SSH transport with hook output (lefthook, husky, pre-commit), errors include "Permission denied (publickey)" or "rejected/non-fast-forward", a pre-push hook fails, or about to debug SSH with `-v`.

Git Push

Preferences for git push, especially diagnosing failures.

Reading push failure output

When git push exits non-zero, output mixes three layers:

• SSH/transport (key offered, accepted)
• Hook driver header (lefthook, husky, pre-commit, etc.)
• Hook output (test/lint/coverage walls)

Identify the failed layer before debugging:

• lefthook or hook: pre-push → pre-push hook failed; transport was fine
• Permission denied (publickey) → SSH auth refused
• ! [rejected] / non-fast-forward → push needs rebase

A wall of test or coverage output is NOT an SSH problem. The hook ran tests, the tests failed, the push was blocked.

pre-push hook failures

Same rules as pre-commit failures in the commit skill: analyze the failures, autofix when possible, ask the user when unclear. Do NOT skip with --no-verify without explicit confirmation.

Debugging SSH

Before adding -v to debug an SSH issue, check whether core.sshCommand is configured:

git config --get core.sshCommand

If it returns nothing, GIT_SSH_COMMAND="ssh -v" git push origin <branch> is fine.

If it returns anything (custom IdentityFile, IdentityAgent, deploy-key flags, etc.), DO NOT use GIT_SSH_COMMAND="ssh -v". It REPLACES core.sshCommand entirely, dropping every flag. Output will look like the wrong keys are being offered, because they are, but only because you removed the constraint.

Append -v to the existing command instead:

GIT_SSH_COMMAND="$(git config core.sshCommand) -v" git push origin <branch>

Background push gotcha

If you started a push with run_in_background and then ran a foreground retry (e.g., because the first looked stuck), the background push may have already succeeded. Before re-investigating "why is push failing":

1. git -C <worktree> log --oneline origin/<branch>..HEAD. Empty output means the push went through.
2. Verify retry's cwd: pwd and git rev-parse --show-toplevel.
3. gh pr view <pr> to see if the commit landed.

Don't escalate to "SSH might be broken" before confirming the push didn't already complete.