Grafo Git
Explica visualmente tus estrategias de ramas
¿Qué es un Grafo Git?
Un grafo Git muestra commits, ramas, merges y tags. Es la forma más clara de documentar tu estrategia de ramas — git flow, trunk-based, release trains — para todo el equipo.
Un grafo Git es material didáctico: su sitio está en CONTRIBUTING.md, en la guía de onboarding, en la discusión sobre si conviene hacer squash. Es el único diagrama cuya sintaxis refleja los comandos que quien lee va a teclear, lo que lo hace fácil de comprobar. Eso sí, no tiene ninguna conexión con tu repositorio: muestra el modelo de ramas que pretendes seguir, nunca el historial que realmente tienes. Tampoco tiene noción de remoto, así que un fork hay que dibujarlo como una rama más.
Ejemplo en directo
gitGraph
commit id: "init"
branch develop
commit id: "setup CI"
branch feature/auth
commit id: "login page"
commit id: "JWT"
checkout develop
merge feature/auth tag: "v0.2.0"
checkout main
merge develop tag: "v1.0.0"Cuándo usarlo
Errores frecuentes
branch también hace checkout
Después de branch develop, todos los commits siguientes caen en develop y no en main. Hay quien añade commits esperando verlos en el tronco y luego se pregunta por qué su línea está vacía: escribe antes checkout main.
El tronco se llama main
checkout master falla con «Trying to checkout branch which is not yet created». Renombra la rama por defecto con una directiva init que fije gitGraph.mainBranchName a master en la primera línea del diagrama.
cherry-pick necesita otra rama
El commit de origen debe existir, llevar el identificador que referencias y estar en una rama distinta. Hacer cherry-pick desde la rama actual falla con «Source commit is already on current branch».
Sintaxis básica
gitGraph
commit
branch develop
commit
checkout main
merge developgitGraph TB:La disposición por defecto va de izquierda a derecha. Añadir TB: pone el grafo en vertical, lo que encaja mucho mejor un historial largo de releases en una página de documentación.
commit id: "hotfix" type: HIGHLIGHT tag: "v1.0.1"Un commit acepta un identificador que puedes referenciar después, un type NORMAL, REVERSE o HIGHLIGHT, y un tag que se dibuja como etiqueta de release sobre la línea.
branch develop order: 2 commitbranch crea la rama y se cambia a ella en un solo paso. El atributo order fija la posición vertical de la línea, para que main se quede donde el lector la espera.
cherry-pick id: "fix-npe"Cherry-pick copia un commit sobre la rama actual: es la forma de mostrar un hotfix retroportado a una línea de release sin volver a dibujar toda la rama.
Preguntas sobre este diagrama
¿Puedo mostrar tags y releases?
Sí — los commits y merges aceptan un atributo tag: (p. ej. tag: "v1.0.0"), perfecto para documentar los puntos de release.
¿Qué estrategias de ramas puede representar?
Cualquiera: git flow, GitHub flow, trunk-based development, ramas de release — la sintaxis refleja las operaciones reales de git (branch, checkout, merge, cherry-pick).
¿Puedo poner un grafo Git en el CONTRIBUTING.md de GitHub?
Sí: un bloque delimitado con la etiqueta mermaid se renderiza en la vista de archivo de GitHub y GitLab. Ese es su sitio natural: las reglas de ramas y su dibujo cambian en el mismo commit y en la misma revisión. Quien revisa recibe un diff, no una captura nueva.
¿Lee el grafo Git mi repositorio real?
No. Se escribe a mano y no sabe nada de tu repositorio, así que no se desviará con tu historial — y tampoco te avisará cuando quede desfasado. Trátalo como un modelo de la estrategia de ramas, no como un log.
¿Cómo represento un rebase o un revert?
No hay palabra clave rebase, así que dibuja el resultado: los commits redibujados sobre la rama de destino. Un revert es commit type: REVERSE, que dibuja el commit tachado en su línea para que se vea que se deshizo.
¿Puede un grafo Git mostrar fechas o un calendario de releases?
No. Los commits están ordenados pero no llevan marca temporal y no hay eje. Acompaña el grafo con una línea de tiempo para las fechas de release, o con un diagrama de Gantt si el tren de releases tiene duraciones y dependencias que merezca la pena planificar.
¿Grafo Git u otro tipo de diagrama?
¿Grafo Git o línea de tiempo?
Los dos son cronológicos. El grafo Git es además ramificado: muestra trabajo que avanza en paralelo y vuelve a unirse. La línea de tiempo es plana. Si lo importante es que dos corrientes se separaron, solo el grafo Git lo hace visible.
¿Grafo Git o diagrama de flujo?
Usa un grafo Git para mostrar qué aspecto tiene el historial, y un diagrama de flujo para mostrar qué debe hacer quien desarrolla. «Sal de main, abre una PR, haz squash-merge» es un procedimiento con decisiones: eso es un diagrama de flujo ilustrado con un grafo Git.
Crea tu Grafo Git ahora
Descríbelo en lenguaje natural — la IA escribe el código Mermaid por ti.
Abrir Mermaid Studio