git describe - Learning Zone

git describe bierze wskazany commit i zwraca dla niego ludzką, czytelną nazwę zbudowaną na bazie najbliższego wcześniejszego taga. Zamiast wklejać komuś goły skrót a1b2c3d, dostajesz coś w stylu v1.4.2-7-ga1b2c3d, czyli: „siedem commitów po tagu v1.4.2″. To ulubione narzędzie skryptów buildowych i CI do automatycznego nadawania numerów wersji — wynik jest stabilny, unikalny i od razu mówi, jak daleko jesteś od ostatniego wydania.

Składnia i najważniejsze opcje

Podstawowa forma: git describe [opcje] [] — bez argumentu opisuje HEAD.

--tags — bierze pod uwagę także tagi lekkie (nieadnotowane), nie tylko git tag -a.
--all — używa dowolnej referencji (gałęzie, remoty), nie tylko tagów.
--always — gdy nie ma żadnego pasującego taga, zwraca skrócony skrót zamiast wywalać błąd.
--long — zawsze pełny format (tag-liczba-gskrot), nawet jeśli commit leży dokładnie na tagu.
--abbrev= — liczba znaków skrótu SHA; --abbrev=0 zwraca samą nazwę taga.
--match — bierze tylko tagi pasujące do wzorca glob, np. 'v*'.
--dirty[=] — dokleja -dirty, jeśli drzewo robocze ma niezacommitowane zmiany.
--contains — odwraca logikę: szuka pierwszego taga, który następuje po commicie.

Przykłady użycia

git describe — opisuje bieżący HEAD względem najbliższego adnotowanego taga.
git describe --tags — to samo, ale liczą się też tagi lekkie (częsty przypadek, gdy ktoś tagował bez -a).
git describe --tags --always --dirty — idealne do skryptów: zawsze coś zwróci i oznaczy brudne drzewo, np. v2.0-3-gabc1234-dirty.
git describe --tags --abbrev=0 — wypluwa tylko nazwę ostatniego taga, bez ogonka — wygodne do „jaka była poprzednia wersja?”.
git describe --contains a1b2c3d — sprawdza, w którym wydaniu wylądował dany commit.

Częste błędy i pułapki

Najczęstsze fatal: No names found, cannot describe anything oznacza, że w historii przed commitem nie ma żadnego adnotowanego taga. Rozwiązanie: dodaj --tags (jeśli używasz lekkich) albo --always (jeśli akceptujesz sam skrót). Pamiętaj, że domyślnie liczą się tylko adnotowane tagi — to klasyczna zasadzka, bo git tag nazwa tworzy tag lekki, którego git describe bez flagi nie zobaczy. Druga pułapka: w płytkim klonie (--depth) lub przy git fetch bez tagów Git może nie mieć historii potrzebnej do znalezienia taga — w CI dociągnij je przez git fetch --tags --unshallow. Zachowanie jest spójne między systemami (Linux, macOS, Windows), więc tu różnic nie ma.

Powiązane komendy: git tag, git log, git rev-parse, git name-rev.