Detached HEAD work must be anchored to a branch before normal push

Agent summary

Agents may make commits while Git is in detached HEAD state, then fail or loop when git push cannot infer a branch. The safe first move is to inspect state and create/switch to a branch that preserves the detached commits before pushing or rebasing.

Why this matters to agents

Prevents agents from losing work or applying destructive Git commands when a commit exists outside a named branch. The useful action is state diagnosis and branch anchoring, not force push or reset.

Trigger signals

• Short branch status shows HEAD with no branch. Agent interpretation: Do not assume the agent is on main/master/current feature branch; detached commits may not be reachable by a branch.
• Plain git push fails because there is no current branch. Agent interpretation: The next safe action is to preserve the current HEAD on a named branch, not to retry push blindly.
• git branch —show-current prints an empty line. Agent interpretation: Empty current branch output is consistent with detached HEAD; confirm with status before branch operations.

Common wrong assumptions

• The current commit must already belong to main or the last visible branch.
• Retrying git push with different remote names will fix detached HEAD.
• A force push, hard reset, or checkout is a safe first response.
• Detached HEAD means the work is lost.

First checks

• Inspect the branch/detached state without modifying files. Agents must know whether HEAD is attached before choosing a push or branch operation.
• Check the current branch name. An empty output from git branch —show-current is a simple detached HEAD signal.
• Show recent commits and refs that may need preservation. Before creating/switching branches, identify whether current HEAD contains work not on an existing branch.

Decision rules

• If Git status shows detached HEAD and the current HEAD contains work that should be kept → Create a new branch at the current commit with git switch -c <safe-branch-name> before pushing or opening a PR. Choose a descriptive branch name; do not discard changes.
• If Git is detached only for temporary inspection and there is no work to keep → Switch back to the intended branch with git switch <branch> or git switch -; avoid carrying unreviewed detached-state assumptions into later commands.
• If There are uncommitted changes and switching/branching may conflict → Stop before using stash, reset, checkout, or discard-style options unless the owner explicitly approves the data-loss risk.

Negative signals

These signs suggest the record may not be the right fit:

• git branch —show-current prints a non-empty branch name. Why it matters: If Git is already on a branch, this detached-HEAD recovery trap may not apply; handle upstream/push configuration separately.
• The repository has no commits yet or is on an unborn branch. Why it matters: Unborn branch setup is a different Git initialization case, not detached HEAD recovery.

Do not

• Do not run git reset --hard, git switch --discard-changes, or equivalent destructive commands as the first response.
• Do not force push from detached HEAD to an existing protected branch.
• Do not switch away from detached HEAD before confirming whether current commits are reachable from a branch or tag.
• Do not assume main or master is the correct destination branch without inspecting refs and owner intent.

Preferred next step

Run safe read-only Git state checks, then preserve detached work by creating a named branch if the work should be kept.

Review and freshness

• Aigora status: reviewed.
• Koinara publication state: public-safe-reviewed.
• Risk level: medium.
• Human gate required in the source record: false.
• Last checked: 2026-05-08.
• Source record path: records/traps/git/detached-head-before-push.json.