---
name: "agent_git"
description: "Git workflows for autonomous agents: atomic commits, branch discipline, secret hygiene, and recovering from bad commits."
---

# Git for Agents

You will commit more often than any human. That makes your habits
load-bearing: sloppy agent commits become an unreadable history, leaked
secrets, and force-push disasters.

## Workflow

1. **Commit atomically.** One commit = one logical change. "Fix login
   bug" and "reformat utils" are two commits. A reviewer needs to revert
   one without the other.
   ```bash
   git add <specific files>     # never git add -A on autopilot
   git commit -m "area: what changed and why"
   ```
   Message shape: `area: imperative summary` — `arena: add stake
   ledger`, not `updates` or `fix stuff`. Put the "why" in the body when
   it isn't obvious from the "what".

2. **Branch for everything non-trivial.**
   ```bash
   git checkout -b feat/stake-ledger
   # ... work, commit, push ...
   git checkout main && git pull && git merge feat/stake-ledger
   ```
   `main` stays deployable. If a change might need review or might
   break, it lives on a branch until it's proven.

3. **Never rewrite shared history.**
   - No `push --force` on `main` or any branch someone else may have
     pulled. Ever.
   - Pushed something bad? Revert it forward: `git revert <sha>`
     creates a new commit that undoes it. History stays honest.
   - `rebase` is for cleaning up *your own* unpushed branch only.

4. **Keep secrets out — permanently.**
   - `.gitignore` gets `*.key`, `*.pem`, `.env`, `credentials*`,
     `secrets*` before the first commit, not after the first leak.
   - `git status` before every commit. If a secret is listed, stop.
   - A committed secret is compromised the instant it's pushed. Rotate
     it — deleting the file in a later commit doesn't un-push it.

5. **Sync deliberately.**
   ```bash
   git pull --rebase   # replay your work on top of theirs: linear history
   git status          # confirm what's yours before pushing
   git push
   ```
   - Pull before starting risky work, not just before pushing.
   - Merge conflicts: read both sides, don't pick one blindly. Conflict
     markers are a question — answer it, don't delete it.

6. **Tag what you deploy.**
   ```bash
   git tag -a v1.4 -m "staked matches live" && git push --tags
   ```
   When production breaks at 2am, "which commit is live?" must have a
   one-command answer.

## Recovery cheatsheet

| Situation | Command |
|---|---|
| Oops, uncommitted changes | `git stash` / `git checkout -- <file>` |
| Bad last commit, unpushed | `git reset --soft HEAD~1` |
| Bad commit, already pushed | `git revert <sha>`, then push |
| Committed on the wrong branch | `git cherry-pick` onto the right one |
| Lost work after a reset | `git reflog` — the commits are still there |

## Operating Rules

1. `git status` before commit, `git log --oneline -5` after push.
   Verify the world matches your mental model, every time.
2. Commit messages are written for a stranger. "WIP" is not a message;
   amend or squash it before it leaves your machine.
3. Never commit generated artifacts that can be rebuilt
   (`node_modules/`, `__pycache__/`, `*.pyc`, build output). If it's
   gitignored upstream, keep it ignored.
4. Large files (>10MB) don't belong in git. Use releases or artifact
   storage; check `du` if a clone feels heavy.
5. When in doubt about a destructive command (`reset --hard`,
   `clean -fd`, force push), stop and ask. These have no undo.