🌿 Mermaid

Grafo Git

Explique visualmente as estratégias de branches

Abrir este exemplo no editor Gerar um com IA

O que é um Grafo Git?

Um grafo Git mostra commits, branches, merges e tags. É a forma mais clara de documentar a sua estratégia de branches — git flow, trunk-based, release trains — para toda a equipa.

Um grafo Git é material pedagógico: pertence ao CONTRIBUTING.md, ao guia de onboarding, à discussão sobre se se deve ou não fazer squash. É o único diagrama cuja sintaxe espelha os comandos que o leitor vai escrever, o que o torna fácil de verificar. Não tem, porém, qualquer ligação ao seu repositório — mostra o modelo de branches que pretende ter, nunca o histórico que tem de facto. Não tem noção de remoto, por isso um fork tem de ser desenhado como uma branch qualquer.

Exemplo em tempo real

Código Mermaid

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"

Exemplo em tempo real

Quando usar

Documentar a estratégia de branches e releases da equipa

Integrar programadores com convenções git visuais

Explicar os procedimentos de hotfix e de release

Erros frequentes

O branch também faz checkout

Depois de branch develop, todos os commits seguintes vão parar a develop e não a main. Há quem acrescente commits a contar que fiquem no tronco e depois estranhe que a faixa esteja vazia — escreva primeiro checkout main se era isso que queria.

O tronco chama-se main

checkout master falha com «Trying to checkout branch which is not yet created». Mude o nome predefinido com uma diretiva init que defina gitGraph.mainBranchName como master, na primeira linha do diagrama.

O cherry-pick precisa de outra branch

O commit de origem tem de existir, tem de trazer o id que referencia e tem de estar noutra branch. Fazer cherry-pick a partir da branch atual falha com «Source commit is already on current branch».

Sintaxe básica

.mmd

gitGraph
    commit
    branch develop
    commit
    checkout main
    merge develop

gitGraph TB:
A disposição predefinida corre da esquerda para a direita. Acrescentar TB: torna o grafo vertical, o que encaixa muito melhor um histórico de releases longo numa página de documentação.
commit id: "hotfix" type: HIGHLIGHT tag: "v1.0.1"
Um commit aceita um id que pode referenciar mais tarde, um type entre NORMAL, REVERSE e HIGHLIGHT, e uma tag desenhada como etiqueta de release na faixa.
branch develop order: 2 commit
O branch cria a branch e muda para ela num só passo. O atributo order fixa a posição vertical da faixa, para que a main fique onde o leitor espera.
cherry-pick id: "fix-npe"
O cherry-pick copia um commit para a branch atual — a forma de mostrar um hotfix retroportado para uma linha de release sem redesenhar a branch inteira.

Perguntas sobre este diagrama

Posso mostrar tags e releases?

Sim — commits e merges aceitam um atributo tag: (p. ex. tag: "v1.0.0"), perfeito para documentar os pontos de release.

Que estratégias de branches pode representar?

Todas: git flow, GitHub flow, trunk-based development, branches de release — a sintaxe reflete as verdadeiras operações git (branch, checkout, merge, cherry-pick).

Posso pôr um grafo Git no CONTRIBUTING.md no GitHub?

Sim — um bloco delimitado com a etiqueta mermaid é renderizado na vista de ficheiro do GitHub e do GitLab. É a sua casa natural: as regras de branches e a imagem que as mostra mudam no mesmo commit e na mesma revisão. Quem revê recebe um diff, não uma nova captura de ecrã.

O grafo Git lê o meu repositório real?

Não. É escrito à mão e não sabe nada do seu repositório, por isso não se desvia com o histórico — e também não o avisa quando fica errado. Trate-o como um modelo da estratégia de branches, não como um log.

Como mostro um rebase ou um revert?

Não existe palavra-chave rebase, por isso desenhe antes o resultado: os commits redesenhados na branch de destino. Um revert é commit type: REVERSE, que renderiza o commit riscado na sua faixa, para o leitor ver que foi desfeito.

Um grafo Git pode mostrar datas ou um calendário de releases?

Não. Os commits estão ordenados mas não têm carimbo temporal e não há eixo. Junte ao grafo uma linha do tempo para as datas de release, ou um gráfico de Gantt quando o comboio de releases tem durações e dependências que vale a pena planear.

Grafo Git ou outro tipo de diagrama?

Grafo Git ou linha do tempo?

Ambos são cronológicos. O grafo Git é cronológico e ramificado: mostra trabalho a decorrer em linhas paralelas e a voltar a juntar-se. A linha do tempo é cronológica e plana. Se o essencial é que dois fluxos divergiram, só o grafo Git o torna visível.

Grafo Git ou fluxograma?

Use um grafo Git para mostrar o aspeto do histórico, e um fluxograma para mostrar o que um programador deve fazer. «Criar branch a partir da main, abrir um PR, fazer squash-merge» é um procedimento com decisões, ou seja, um fluxograma ilustrado por um grafo Git.

Explorar outros tipos de diagramas

🔀 Fluxograma 💬 Diagrama de sequência 🧩 Diagrama de classes 🗄️ Diagrama entidade-relação 🔄 Diagrama de estados 📅 Gráfico de Gantt 🥧 Gráfico circular 🧠 Mapa mental 🕰️ Linha do tempo 🚶 Jornada do utilizador 🎯 Gráfico de quadrantes

Crie já o seu Grafo Git

Descreva-o em linguagem natural — a IA escreve o código Mermaid por si.

Abrir o Mermaid Studio