Grafo Git
Spiega visivamente le strategie di branching
Che cos’è un Grafo Git?
Un grafo Git mostra commit, branch, merge e tag. È il modo più chiaro per documentare la tua strategia di branching — git flow, trunk-based, release train — per tutto il team.
Un grafo Git è materiale didattico: sta nel CONTRIBUTING.md, nella guida di onboarding, nella discussione se fare squash o no. È l’unico diagramma la cui sintassi rispecchia i comandi che il lettore digiterà, e questo lo rende facile da verificare. Non ha però alcun legame con il tuo repository: mostra il modello di branching che hai in mente, mai la cronologia che hai davvero. Non ha alcuna nozione di remote, quindi un fork va disegnato come un branch qualsiasi.
Esempio dal vivo
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"Quando usarlo
Errori frequenti
branch fa anche il checkout
Dopo branch develop, ogni commit successivo finisce su develop e non su main. Si aggiungono commit credendoli sul tronco e poi ci si chiede perché la sua corsia è vuota: scrivi prima checkout main, se era quello che intendevi.
Il tronco si chiama main
checkout master fallisce con «Trying to checkout branch which is not yet created». Rinomina il ramo predefinito con una direttiva init che imposta gitGraph.mainBranchName a master sulla prima riga del diagramma.
Il cherry-pick richiede un altro branch
Il commit di origine deve esistere, deve portare l’id a cui fai riferimento e deve stare su un branch diverso. Un cherry-pick dal branch corrente fallisce con «Source commit is already on current branch».
Sintassi di base
gitGraph
commit
branch develop
commit
checkout main
merge developgitGraph TB:Il layout predefinito va da sinistra a destra. Aggiungere TB: rende il grafo verticale, cosa che fa entrare molto meglio una lunga storia di release in una pagina di documentazione.
commit id: "hotfix" type: HIGHLIGHT tag: "v1.0.1"Un commit accetta un id a cui fare riferimento più avanti, un type tra NORMAL, REVERSE e HIGHLIGHT, e un tag disegnato come etichetta di release sulla corsia.
branch develop order: 2 commitbranch crea il branch e ci si sposta sopra in un colpo solo. L’attributo order fissa la posizione verticale della corsia, così main resta dove il lettore se lo aspetta.
cherry-pick id: "fix-npe"Il cherry-pick copia un singolo commit sul branch corrente: è il modo di mostrare un hotfix riportato su una linea di release senza ridisegnare tutto il branch.
Domande su questo diagramma
Posso mostrare tag e release?
Sì — commit e merge accettano un attributo tag: (es. tag: "v1.0.0"), perfetto per documentare i punti di release.
Quali strategie di branching può rappresentare?
Tutte: git flow, GitHub flow, trunk-based development, branch di release — la sintassi rispecchia le vere operazioni git (branch, checkout, merge, cherry-pick).
Posso mettere un grafo Git nel CONTRIBUTING.md su GitHub?
Sì: un blocco di codice con il tag mermaid viene renderizzato nella vista del file su GitHub e GitLab. È la sua casa naturale: le regole di branching e la loro illustrazione cambiano nello stesso commit e nella stessa revisione. Chi rivede riceve un diff, non un nuovo screenshot.
Il grafo Git legge il mio repository reale?
No. È scritto a mano e non sa nulla del tuo repo, quindi non va alla deriva con la tua cronologia — ma non ti avvisa nemmeno quando diventa sbagliato. Consideralo un modello della strategia di branching, non un log.
Come mostro un rebase o un revert?
Non esiste una parola chiave rebase: disegna il risultato, cioè i commit ridisegnati sul branch di destinazione. Un revert è commit type: REVERSE, che disegna il commit barrato sulla sua corsia, così si vede che è stato annullato.
Un grafo Git può mostrare date o un calendario di release?
No. I commit sono ordinati ma non portano timestamp e non esiste alcun asse. Affianca al grafo una linea temporale per le date di release, o un diagramma di Gantt quando il release train ha durate e dipendenze da pianificare.
Grafo Git o un altro tipo di diagramma?
Grafo Git o linea temporale?
Entrambi sono cronologici. Il grafo Git è cronologico e ramificato: mostra il lavoro che procede su linee parallele e poi si ricongiunge. La linea temporale è cronologica e piatta. Se il punto è che due flussi si sono separati, solo il grafo Git lo rende visibile.
Grafo Git o diagramma di flusso?
Usa un grafo Git per mostrare com’è fatta la cronologia, e un diagramma di flusso per mostrare che cosa deve fare uno sviluppatore. «Parti da main, apri una PR, fai squash-merge» è una procedura con delle decisioni: un diagramma di flusso, illustrato da un grafo Git.
Crea ora il tuo Grafo Git
Descrivilo in linguaggio naturale — l’IA scrive il codice Mermaid per te.
Apri Mermaid Studio