Graf Git
Objaśniaj strategie gałęzi wizualnie
Czym jest Graf Git?
Graf Git pokazuje commity, gałęzie, merge i tagi. To najczytelniejszy sposób dokumentowania strategii gałęzi — git flow, trunk-based, release trains — dla całego zespołu.
Graf Git to materiał szkoleniowy: jego miejsce jest w pliku CONTRIBUTING.md, w przewodniku onboardingowym, w sporze o to, czy squashować. To jedyny diagram, którego składnia odwzorowuje polecenia wpisywane przez czytelnika, dzięki czemu łatwo go sprawdzić. Nie ma jednak żadnego połączenia z Twoim repozytorium — pokazuje model gałęzi, który zamierzasz stosować, nigdy historię, którą naprawdę masz. Nie zna też pojęcia repozytorium zdalnego, więc fork trzeba narysować jako zwykłą gałąź.
Żywy przykład
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"Kiedy go używać
Częste błędy
branch od razu przełącza
Po branch develop każdy kolejny commit ląduje na develop, a nie na main. Ludzie dopisują commity, spodziewając się ich na głównym pniu, a potem dziwią się, że jego pas jest pusty — jeśli o to Ci chodziło, napisz najpierw checkout main.
Pień nazywa się main
checkout master kończy się błędem „Trying to checkout branch which is not yet created”. Nazwę domyślnej gałęzi zmienisz dyrektywą init ustawiającą gitGraph.mainBranchName na master w pierwszej linii diagramu.
cherry-pick wymaga innej gałęzi
Commit źródłowy musi istnieć, musi nieść identyfikator, do którego się odwołujesz, i musi leżeć na innej gałęzi. Cherry-pick z bieżącej gałęzi kończy się błędem „Source commit is already on current branch”.
Podstawowa składnia
gitGraph
commit
branch develop
commit
checkout main
merge developgitGraph TB:Domyślny układ biegnie z lewej do prawej. Dodanie TB: obraca graf w pionie, co znacznie lepiej mieści długą historię wydań na stronie dokumentacji.
commit id: "hotfix" type: HIGHLIGHT tag: "v1.0.1"Commit przyjmuje identyfikator, do którego można się później odwołać, typ NORMAL, REVERSE albo HIGHLIGHT oraz tag rysowany na pasie jako etykieta wydania.
branch develop order: 2 commitbranch tworzy gałąź i od razu na nią przełącza. Atrybut order ustala pionowe położenie pasa, dzięki czemu main zostaje tam, gdzie czytelnik go oczekuje.
cherry-pick id: "fix-npe"Cherry-pick kopiuje jeden commit na bieżącą gałąź — tak pokazuje się hotfix przeniesiony na linię wydania bez przerysowywania całej gałęzi.
Pytania o ten diagram
Czy mogę pokazać tagi i wydania?
Tak — commity i merge przyjmują atrybut tag: (np. tag: "v1.0.0"), idealny do dokumentowania punktów wydań.
Które strategie gałęzi można przedstawić?
Każdą: git flow, GitHub flow, trunk-based development, gałęzie release — składnia odwzorowuje prawdziwe operacje gita (branch, checkout, merge, cherry-pick).
Czy mogę wstawić graf Git do pliku CONTRIBUTING.md na GitHubie?
Tak — blok ogrodzony z oznaczeniem mermaid renderuje się w widoku pliku na GitHubie i GitLabie. To jego naturalne miejsce: reguły gałęzi i ich obrazek zmieniają się w tym samym commicie i w tym samym przeglądzie. Recenzenci dostają różnicę, a nie kolejny zrzut ekranu.
Czy graf Git czyta moje repozytorium?
Nie. Pisze się go ręcznie i nic nie wie o Twoim repozytorium, więc nie rozjedzie się z historią — ale też nie ostrzeże, gdy stanie się nieprawdziwy. Traktuj go jak model strategii gałęzi, a nie jak log.
Jak pokazać rebase albo revert?
Słowa kluczowego rebase nie ma, więc narysuj wynik: commity przerysowane na gałąź docelową. Revert to commit type: REVERSE, który renderuje commit przekreślony na jego pasie, więc czytelnik widzi, że został cofnięty.
Czy graf Git pokaże daty albo harmonogram wydań?
Nie. Commity mają kolejność, ale nie mają znaczników czasu, i nie ma tu żadnej osi. Do dat wydań dołóż oś czasu, a wykres Gantta wtedy, gdy pociąg wydaniowy ma czasy trwania i zależności warte zaplanowania.
Graf Git czy inny typ diagramu?
Graf Git czy oś czasu?
Oba są chronologiczne. Graf Git jest chronologiczny i rozgałęziony: pokazuje pracę toczącą się na równoległych liniach i wracającą do siebie. Oś czasu jest chronologiczna i płaska. Jeśli sedno leży w tym, że dwa nurty się rozeszły, uwidoczni to tylko graf Git.
Graf Git czy schemat blokowy?
Grafem Git pokazujesz, jak wygląda historia, a schematem blokowym — co deweloper ma zrobić. „Odbij gałąź od main, otwórz pull requesta, scal ze squashem” to procedura z decyzjami, czyli schemat blokowy zilustrowany grafem Git.
Stwórz swój Graf Git już teraz
Opisz go naturalnym językiem — AI napisze kod Mermaid za Ciebie.
Otwórz Mermaid Studio