Robiąc research do Kolejnej Książki o Gicie, trafiłem na polecenie git notes. Myślałem, że dość dobrze znam Gita, jednak to było dla mnie coś nowego. W tym artykule przedstawię Ci, czym są git notes, jakie zastosowania dla nich znalazłem i czy faktycznie jest to najbardziej bezużyteczna funkcja Gita.

Czym są git notes?

Polecenie git notes służy do dodawania notatek do obiektów Gita, takich jak commity czy tagi typu annotated. Istotne jednak jest, że notatka nie stanowi integralnej części obiektu. Pozwala to na dodanie dodatkowych informacji, metadanych czy kontekstu zmian bez bezpośredniego umieszczania ich np. w commit message, dzięki czemu nie zmieniamy też SHA obiektu. Jest to szczególnie istotne, gdy nie jesteśmy jedynym użytkownikiem repozytorium. Chcąc zaktualizować np. commit message w istniejącym commicie, konieczne będzie przepisanie historii, co będzie kłopotliwe przy pracy w zespole.

By utworzyć notatkę, należy wykorzystać polecenie git notes add. By pominąć interakcję z edytorem, podobnie jak w przypadku git commit można skorzystać ze skróconego wariantu git notes add -m "treść notatki". Domyślnie notatka zostanie stworzona dla commita będącego HEAD. Można również wskazać konkretny obiekt, podając jego SHA na końcu polecenia.

Po utworzeniu notatki i wywołaniu polecenia git log, pod opisem ostatniego commita ukaże się również treść notatki pod nagłówkiem Notes:. Treść notatki można również podejrzeć poleceniem git notes show <SHA>.

Git pozwala na dodanie jednej notatki na obiekt w ramach jednej przestrzeni nazw. Próba dodania kolejnej notatki w tej samej przestrzeni spowoduje błąd, chyba że użyjemy parametru -f, który spowoduje nadpisanie poprzedniej notatki. Domyślną przestrzenią nazw jest commits. By dodać notatkę w innej przestrzeni nazw, należy użyć parametru --ref <namespace>.

git notes add -m "foo"
git notes --ref test -m "bar"

git notes show // foo
git notes --ref commits show // foo
git notes --ref test // bar

Dzięki wykorzystaniu przestrzeni nazw można dodawać notatki np. per użytkownik czy np. zawierające referencje do zasobów w zewnętrznych systemach.

Git oferuje również możliwość edycji, usuwania czy kopiowania notatek, jednak po ich szczegółowy opis odsyłam już do dokumentacji.

Problemy

Bazując na podanym opisie, wydaje się, że git notes są potencjalnie użytecznym dodatkiem, który w pewnych przypadkach mógłby mieć zastosowanie. Mają jednak kilka mankamentów, które w mojej ocenie obniżają ich efektywność.

Pierwszy problem to niska świadomość ich istnienia. Notatki nie są częstym tematem książek, kursów czy artykułów dotyczących Gita. Jeśli w ogóle, to są przedstawione jako ciekawostka.

Drugi problem to brak ich domyślnej synchronizacji do repozytorium zdalnego. Referencje do notatek nie są objęte standardowym zakresem poleceń git push i git pull. W połączeniu z niską świadomością istnienia notek istnieje mała szansa, że ktoś je pobierze, jeśli nie będzie to elementem sposobu pracy przyjętego w projekcie.

By wysłać notatki do repozytorium zdalnego, konieczne jest wywołanie polecenia git push origin "refs/notes/*" lub skonfigurować odpowiednio repozytorium dodając wpis remote.origin.push "+refs/notes/*:refs/notes/*" w konfiguracji. Każda przestrzeń nazw to osobny ref (refs/notes/<namespace>). Możesz więc też wysłać tylko wybrane notatki, a nie wszystkie na raz.

Analogicznie by dokonać fetcha notek, trzeba wywołać polecenie git fetch origin refs/notes/*:refs/notes/* lub skonfigurować Gita tak, by pobierał notes automatycznie przy wywołaniu git fetch (klucz remote.origin.fetch).

Trzeci problem to brak wsparcia w niektórych popularnych narzędziach do pracy z Gitem. Przykładowo w GitHubie od 2014 roku notatek nie podejrzymy.

Use cases dla git notes

Analizę wykorzystania git notes zacząłem od sprawdzenia, jak inni je wykorzystują. W jednym z artykułów natknąłem się na kilka propozycji:

• Tracking time spent per commit or branch
• Adding review and testing information to git log
• And even fully distributed code review

Moim zdaniem są one nieco chybione. Przede wszystkim są do tego dedykowane narzędzia. Trackowanie czasu zwykle odbywa się w dedykowanym narzędziu, które pamięta czas i pozwala powiązać wpisy z konkretnym zadaniem.

Punkty dotyczące code review są moim zdaniem jeszcze bardziej chybione. Obecne systemy do robienia code review oferują znacznie więcej niż zostawienie notatki pod commitem. Z drugiej strony są narzędzia, które wykorzystują git notes do code review. Mój sceptycyzm więc może wynikać z braku przetestowania tego rozwiązania w praktyce. Jeśli korzystałeś/aś z takiego systemu, jestem bardzo ciekaw, jak sprawdza się w praktyce!

Przypadkiem, w którym git notes mogą znaleźć zastosowanie, jest sytuacja, gdy korzystamy ze skryptów lub automatyzacji. Dla konkretnych commitów mogą one potrzebować tymczasowo zapisać jakieś metadane. Czasami nie chcemy lub nie możemy ich przechowywać w pamięci lub bazie. Ciekawym przykładem jest case opisany na forum GitLaba, gdzie użytkownik wykorzystuje notki do automatycznego linkowania commitów z ticketami z zewnętrznego systemu. Inny artykuł pokazuje, jak użyć git notes w pipeline CI/CD.

Moim zdaniem w codziennej pracy raczej nie sprawdzą się przypadki wymagające samodzielnego pusha notatek do repozytorium zdalnego i zespołowej pracy z nimi. Nawet jeśli twórca notatki skonfiguruje repozytorium, by automatycznie je wysyłać i pobierać, to nie mamy gwarancji, że inni też to zrobili.

Postanowiłem zapytać Chata GPT (wersja 5), jakie widzi zastosowania dla git notes i poza już omówionymi podał kilka dodatkowych przykładów:

• Dodawanie informacji do commitów bez ich przepisywania — zgadzam się, że jest to zaleta, jednak chcąc dodać ważną informację do commita, powinna być ona łatwa do znalezienia. W git notes istnieje spora szansa, że ktoś do nich nie zajrzy. Jeśli jest to faktycznie ważna informacja, moim zdaniem warto przepisać historię. W przypadku mniej istotnych informacji zgadzam się, że racjonalne jest użycie git notes.
• Podpisywanie commitów przez QA/PM — moim zdaniem bardziej odpowiednim miejscem do takich notatek jest Trello, Jira, czy inne narzędzia. W tym przypadku git notes jest OK, ale raczej jako dodatek, a nie główne miejsce do składowania takiej informacji.
• Tymczasowe komentarze developerskie — ten przypadek jest całkiem trafny. Osobiście jednak zamieściłbym je w kodzie, a jeśli miałyby być prywatne, to skorzystałbym ze stasha. To jest jednak już kwestia preferencji, a nie obiektywnej oceny czy notatki są odpowiednim miejscem na takie rzeczy. W tym przypadku jednak istnieje ryzyko konfliktów, czego nie ma w przypadku git notes.

Podsumowanie

Jestem ciekaw czy kiedykolwiek korzystałeś/aś z git notes. Jeśli tak, to koniecznie daj znać w komentarzu. Jestem ogromnie ciekaw, jakie zastosowanie znalazłeś dla tej funkcji. Prawo nagłówków Betteridge’a tym razem zadziałało i nie nazwałbym tej funkcji najbardziej bezużyteczną. Z pewnością nie jest to jednak kluczowa funkcja Gita czy sprawdzająca się w codziennym flow pracy. Zastosowanie notatek widzę głównie w miejscach, gdzie „komputer rozmawia z komputerem”, czy przechowywania dodatkowych metadanych w commitach.

Jeśli zaś interesują Cię bardziej przydatne możliwości Gita, to koniecznie sprawdź Kolejną Książkę o Gicie — mój e-book, który pozwoli Ci podnieść umiejętności pracy z Gitem na znacznie wyższy poziom.

Artykuł jest autopromocją Kolejnej Książki o Gicie.

Źródła i materiały dodatkowe

• Tyler Cipriani – Git Notes: git’s coolest, most unloved­ feature
• Abin Simon – Just a bunch of git stuff
• Dokumentacja Gita – git notes
• GitLab – Add support for git-notes in commit messages
• GitLab – Make Git Notes visible in the UI
• Git appraise – Distributed Code Review For Git
• Lee Hambley – Effortlessly maintain a high quality change log with Git notes
• Scott Chacon – Git Notes Display
• Michael Graf – Improve your CI-CD-Workflow with Git-Notes

Zaobserwuj mnie w mediach społecznościowych!

LinkedIn jest głównym medium, poza blogiem, gdzie publikuję swoje przemyślenia. Zachęcam też do zaobserwowania devszczepaniak.pl na Facebooku, gdzie oprócz informacji o nowych artykułach publikuję linki do ciekawych treści.

Udostępnij wpis

Szukasz taniego i dobrego VPS? Skorzystaj z Mikrusa i przy zakupie odbierz dodatkowy miesiąc usługi za darmo!

📖 Koniecznie sprawdź ofertę księgarni Helion oferującej tysiące książek dla programistów w dobrych cenach! Kupując z tego linku, pomagasz w rozwoju bloga.

Chcesz docenić moją pracę? Postaw mi kawę!