git rev-parse para coding agents: SHA, rama y cwd, no folklore

git rev-parse no inspecciona un commit ni camina historia. El man (git-rev-parse(1), Git 2.50.1 / Apple Git-155; git-scm.com/docs/git-rev-parse HTTP 200, last-modified 2026-08-31) pick out and massage parameters: resuelve un <arg> a objeto, ref o path. HEAD, index y working tree no se mueven. Fuera de un repo: fatal: not a git repository, exit 128 — salvo --parseopt y --sq-quote, que el man deja usar fuera y un agente no necesita para “cuál es HEAD”.

gitrevisions(7) (HTTP 200, last-modified 2026-08-31) es la gramática: SHA, HEAD, @, feat, HEAD~1, HEAD^{commit}, HEAD:src/foo.ts. Esta guía no sustituye show (el objeto) ni log (el walk). El contrato: verificar que el nombre existe, obtener el SHA o el path, y parar en 128.

GitHub Docs (Getting permanent links to files, HTTP 200 2026-09-04): un permalink blob/<sha>/path ancla el file a un commit de github.com. No es rev-parse de tu worktree. Un agente que quiere “el SHA de este clone” corre git rev-parse; el que quiere un link permanente en el remoto copia el permalink de la UI, no inventa 40 hex.

Lo que el agente sí / no corre

Quiero	Comando	Trampa
¿Existe este nombre?	git rev-parse --verify --quiet --end-of-options -- "$rev"	git rev-parse $rev y parsear el fatal
SHA completo	git rev-parse --verify --end-of-options -- "$rev^{commit}"	7 hex del log “porque alcanza”
Rama actual	git rev-parse --abbrev-ref HEAD	git branch al LLM
Ref completa	git rev-parse --symbolic-full-name HEAD	asumir refs/heads/main en detached
Raíz del worktree	git rev-parse --show-toplevel	pwd o find .git
¿Hay upstream?	git rev-parse --verify --quiet '@{u}'	@{u} sin comillas (el shell come {})

Prohibido en autónomo:

• --all / --branches / --tags / --remotes / --glob. El man lista todas las refs. Dump al prompt.
• --parseopt / --sq-quote. El man: modos de parsing/quoting, válidos fuera del repo. No resuelven HEAD.
• --not. Prefija ^ (verificado: ^<sha>). Eso es input de log, no un SHA para show.
• --disambiguate=<prefix> “por si el short choca”. El man: el prefix debe tener ≥4 hex; si no, lista cada objeto. Un agente nombra el SHA que ya tiene.
• --quiet sin --verify. El man: Only meaningful in --verify mode. Verificado 2026-09-04: git rev-parse --quiet NOPE imprime ambiguous argument y sale 128. Con --verify --quiet NOPE no hay mensaje y sale 1.
• Un nombre de fuente no confiable sin --end-of-options. El man: wise to use --end-of-options so that the name argument is not mistaken for another option.
• Sustituir esto por el SHA de la UI de GitHub. El permalink mira el remoto; tu worktree puede estar en otra rama.

--short[=<n>] es --verify recortado. El man: mínimo 4; default = core.abbrev. Verificado: --short=3 HEAD igual imprimió 4 hex. Sin argumento: Needed a single revision, 128.

Exit con --verify: 0 y SHA en stdout si el nombre existe; 128 y Needed a single revision si no (o si no pasas exactamente un parámetro). --quiet cambia el fallo a 1 silencioso. Verificado: --verify vacío → 128; --verify NOPE → 128; --verify --quiet NOPE → 1; --verify HEAD → 0 y 40 hex.

Receta (60 segundos)

Solo en un worktree propio:

git rev-parse --is-inside-work-tree   # true; 128 = no estás en un repo
git rev-parse --abbrev-ref HEAD       # main | HEAD si detached
git rev-parse --verify --quiet --end-of-options -- HEAD
git rev-parse --show-toplevel

Si el ticket nombra un SHA o una rama:

git rev-parse --verify --quiet --end-of-options -- "${rev}^{commit}" || exit 1

^{commit} (el man: peeling operator) exige un commit-ish. Verificado: HEAD^{blob} → expected blob type, but the object dereferences to tree type, 128. HEAD^{object} acepta cualquier tipo. HEAD^{tree} es el tree del commit, no el commit.

@{u} / @{upstream} sin tracking: no upstream configured for branch, 128. origin/main si no hay remote: Needed a single revision, 128. No “arregles” con un SHA de memoria; fetch primero si el ticket pide el remoto.

Paths y booleanos

Flag	En la raíz	Desde sub/	Fuera del repo
--show-toplevel	absoluto del worktree	el mismo absoluto	128
--show-prefix	línea vacía	sub/	128
--show-cdup	línea vacía	../	128
--git-dir	.git (relativo al cwd)	.git vía discovery	128
--absolute-git-dir	absoluto de .git	el mismo absoluto	128
--is-inside-work-tree	true	true	128, no false
--is-inside-git-dir	false	false; true si cwd es .git	128
--is-bare-repository	false	false	128

Verificado 2026-09-04: cd /tmp && git rev-parse --is-inside-work-tree no imprime false; imprime not a git repository y sale 128. Un agente que parsea true/false debe tratar 128 como “no hay repo”, no reintentar.

--path-format=absolute|relative (el man) afecta a --git-dir, --show-toplevel y similares después de esa flag. --absolute-git-dir no depende de ella.

Detached: --abbrev-ref HEAD imprime HEAD; --symbolic-full-name HEAD también HEAD (no refs/heads/…). Verificado tras git switch --detach. Un agente que asume “estamos en main” porque el clone se llamaba main se equivoca.

Checklist

• Worktree propio. 128 de --is-inside-work-tree = para.
• --verify --quiet --end-of-options -- + peeling ^{commit} si hace falta un commit.
• --abbrev-ref HEAD para el nombre corto; --symbolic-full-name si vas a escribir un ref.
• Cero --all, --not, --parseopt, --quiet suelto.
• @{u} entrecomillado. 128 = no hay upstream, no hay SHA.
• Permalink de GitHub no sustituye el SHA local.

FAQ

¿git rev-parse HEAD sin --verify? El man acepta varios <arg> y modos. Sin --verify un typo puede mezclarse con flags (--end-of-options HEAD sin --verify reimprimió el flag y el SHA). --verify fuerza un objeto o 128/1.

¿--short vs 7 hex del log? --short es único en este repo ahora. El man recorta a un prefix no ambiguo (≥4). Un SHA de 7 copiado de otro clone puede colisionar. Para scripts: 40 hex de --verify.

¿Esto reemplaza reflog? No. HEAD@{1} es gramática de gitrevisions(7); rev-parse --verify 'HEAD@{1}' solo resuelve. El reflog lista el log. Sin comillas el shell parte {}.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. rev-parse no es show: nombra el objeto; no lo imprime.

Verificado 2026-09-04 contra git-rev-parse(1) (Git 2.50.1 / Apple Git-155; git-scm.com/docs/git-rev-parse HTTP 200, last-modified 2026-08-31), gitrevisions(7) (HTTP 200) y GitHub Docs “Getting permanent links to files” (HTTP 200). En esta máquina: --verify vacío o NOPE exit 128; --verify --quiet NOPE exit 1 silencioso; --quiet NOPE sin --verify exit 128 con fatal; @{u} sin upstream 128; fuera del repo --is-inside-work-tree 128; detached --abbrev-ref HEAD = HEAD; HEAD^{blob} 128; --short=3 sigue emitiendo ≥4 hex.