git show-branch para coding agents: el grafo semi-visual de 26 puntas

git show-branch dibuja la ancestralidad de varias puntas a la vez en un formato semi-visual: una cabecera por rama, una línea ---, y debajo un log donde cada commit lleva una columna de signos por rama. El man (git-show-branch(1); git-scm.com/docs/git-show-branch HTTP 200 verificado 2026-09-06; pie del man local Git 2.54.0, 2026-04-19; binario Git 2.50.1 / Apple Git-155) lo dice en dos frases: muestra el grafo "semi-visually" y no puede mostrar más de 26 ramas y commits a la vez.

Para un coding agent es una herramienta de lectura con techo duro. No escribe. No mueve HEAD. No toca el index. Su salida es para que un humano entienda de un vistazo qué rama contiene qué — no para parsear en un pipeline. Si necesitas machine-readable, eso es for-each-ref.

No es git branch -a (lista puntas, sin ancestralidad). No es log --graph (dibuja líneas, no una matriz de pertenencia por rama). No es merge-base: show-branch tiene un modo --merge-base con semántica distinta. Vive en el hub comparativas y decisiones.

Anatomía de la salida

Con N refs, las primeras N líneas son la descripción de una línea de cada punta. La rama apuntada por HEAD lleva prefijo *; las demás, !. Después viene --- y el log: si un commit está en la rama I-ésima, el carácter de indentación I-ésimo muestra +; si no, espacio; los merges se marcan con -. Cada commit además recibe un nombre corto usable como extended SHA (topic2, topic2~1).

Verificado 2026-09-06 en un repo con main (commit base), topic1 (misma base) y topic2 (un commit propio, checkout actual):

! [main] base
 ! [topic1] base
  * [topic2] t2
---
  * [topic2] t2
++* [main] base

Tres columnas de signos, tres ramas. ++* = el commit base vive en las tres; * = t2 solo en topic2. Ese es el valor del comando: contención mutua de un vistazo, algo que branch -a jamás responde.

Flag	Qué cambia	Cuándo
--list	sinónimo de --more=-1: solo las puntas, sin grafo	cuando quieres el bloque de arriba y nada más
--more=<n>	sigue n commits más allá del ancestro común	ramas muy divergentes
--independent	solo las refs inalcanzables desde las demás	detectar puntas que realmente aportan commits nuevos
--merge-base	posibles bases de merge entre los commits dados	preparación de un merge real
--topics	oculta commits ya en la primera rama	ver qué hay fuera de la línea principal
-g[=<n>[,<base>]]	modo reflog: últimas entradas de una ref	auditoría de movimientos de una rama
--topo-order / --date-order	orden topológico vs cronológico	salidas largas
--sparse	incluye merges alcanzables desde una sola punta	grafo completo
--no-name / --sha1-name	sin nombres / nombres por prefijo SHA	salida compacta

--more, --list, --independent y --merge-base son mutuamente excluyentes (el man lo declara; verificado: combinar --list --independent devuelve usage).

Los modos que confundir

--independent no imprime el formato [rama]. Verificado 2026-09-06: git show-branch --independent main topic1 topic2 devolvió 147900b927d057b2bcb79df635d3631006b40f02 — un SHA crudo, la única punta que no está en otra. topic1 apunta al mismo commit que main, así que desaparece. Útil para saber "¿qué ramas tienen commits que nadie más tiene?", pero es plumbing: ni nombre de rama.

--topics toma la PRIMERA rama como línea principal y muestra solo lo que no está en ella; el man lo define como equivalente a git rev-list ^master topic1 topic2 (ver rev-list). Si el orden de argumentos cambia, cambia el resultado: show-branch --topics main topic1 no es lo mismo que --topics topic1 main.

-g (reflog) es otro comando disfrazado: lee entradas de reflog (topic2@{0}, topic2@{1}) con timestamp y acción (commit: t2, branch: Created from HEAD), no commits del grafo. <base> acepta count o date (--reflog="10,1 hour ago"). Sin <ref> explícito, usa la rama actual (o HEAD si está detached). Para historial de ref con nombres completos, reflog sigue siendo la fuente; show-branch solo la pinta.

El techo de 26 (y por qué existe)

Cada rama ocupa una columna en la matriz de signos; solo hay 26 letras disponibles para los nombres cortos, por eso el man fija el límite: "It cannot show more than 26 branches and commits at a time". En un repo con 80 ramas temáticas, show-branch --all simplemente no es una salida válida: pasa el filtro. Un agente que lo intente obtendrá truncado silencioso o error, no un error claro — la mitigación es no hacer del flag una opción: pasa globs o refs explícitas (show-branch topic/*) y usa el config showBranch.default (multi-valued) para fijar el set por defecto del humano, algo como default = --topo-order + default = heads/*.

Contrato para el agente

1. Read-only. No hay flags destructivos; el riesgo real es interpretar mal una salida ambigua, no corromper el repo.
2. Exit 128 con ref inválida. Verificado 2026-09-06: git show-branch nope-xyz → fatal: bad sha1 reference nope-xyz, exit 128. No confundir con un "repo sin ramas": una rama que no existe falla igual que un typo.
3. Sin args no es "todo": muestra las refs bajo refs/heads/refs/tags (más el config showBranch.default si existe), no --all. Si quieres remote-tracking, --remotes o --all explícitos.
4. El grafo se para en el ancestro común. Con --more mal calibrado, el agente ve tres líneas y cree que las ramas convergen; a veces solo cortó pronto.
5. Para decisiones de merge, usa su herramienta. --merge-base muestra bases posibles entre los commits dados; el man aclara que maneja distinto el caso de tres o más commits que git merge-base. Si el agente necesita la base para un merge real, ve a merge-base, no a parsear columnas de signos.

Show-branch vs otras herramientas de "ver ramas"

Necesidad	Herramienta	Por qué
Ver contención mutua de pocas ramas	show-branch	matriz de signos, única
Listar todas las puntas sin más	git branch -a / show-ref	sin grafo, sin techo
Salida para script	for-each-ref --format	templatable
¿Qué trae esta rama vs main?	show-branch --topics main topic/* o rev-list --count	el primero pinta, el segundo cuenta
Commits por autor/agregado	shortlog / log	show-branch no agrega
¿Cuándo se movió la rama?	reflog / show-branch -g	el reflog tiene acción y timestamp

Checklist antes de ejecutar show-branch

• ¿Paso refs o globs explícitos en vez de --all? (techo de 26)
• ¿Solo puntas? --list, sin grafo.
• ¿Diferencias reales entre ramas? --independent (SHA crudo, cero nombres) o --topics primera-rama.
• ¿Base para merge? --merge-base o el merge-base canónico.
• ¿Ref inválida? exit 128 — tratar como error propio, no como repo vacío.
• ¿Necesito parsear? No: for-each-ref.

FAQ

¿Por qué mi rama no aparece con show-branch --list y sí con git branch? --list respeta showBranch.default si está configurado y el set por defecto (refs/heads + refs/tags), no --all. Las remote-tracking solo salen con --remotes/--all.

¿++* significa que el commit está fusionado? No. Significa que el commit es alcanzable desde las tres puntas. Que alguien hiciera un merge o solo un branch en el mismo punto es indiferente para la matriz.

¿Puedo pedirle al agente que "resuma las ramas" con show-branch? Puede, para 26 puntas o menos y con salida legible. Para inventarios de 200 ramas o para decisiones automatizadas, el techo y el formato semi-visual lo hacen peor opción que plumbing.

¿-g muestra el reflog de todas las ramas? De una sola ref por llamada; sin <ref>, la rama actual. Itera refs si necesitas el historial completo.

Si tu agente pasa de "pintar el grafo" a decidir sobre él, el siguiente paso es entender qué stdout es seguro parsear y cuál no: la serie completa de plumbing vive en el hub, y para el flujo de trabajo con un agente de código desde cero está el curso Instalar un agente IA.