Git Notes: Git’in En Havalı ve En Sevilmeyen Özelliği (2022)

 (tylercipriani.com)
3 puan yazan GN⁺ 2025-06-23 | 1 yorum | WhatsApp'ta paylaş
  • Git notes, Git nesnelerini değiştirmeden ayrı bir ad alanında metadata eklemeyi sağlayan bir özellik olsa da, düşük kullanılabilirlik ve sınırlı benimsenme nedeniyle yaygın olarak kullanılmıyor
  • Eski commit mesajlarını düzeltmek gerekmeksizin yeni bilgiler eklenebildiği için, inceleme·build·ticket bilgileri gibi otomasyon sistemlerinin bıraktığı kayıtlar için oldukça uygun
  • Git projesi ve Gerrit, notes özelliğini gerçekten kullanıyor; böylece commit başına e-posta listesi tartışmaları, test sonuçları ve reviewer bilgileri git log içinde görülebiliyor
  • Google’ın git-appraise aracı, git notes üzerine dağıtık kod incelemesi kuruyor; inceleme isteği, yorum, inceleme ve birleştirme işlemleri yerelde yapılabiliyor
  • GitHub, 2014’te commit notes gösterimini durdurdu; ayrıca blob·tree notes kullanmak, Git’in iç komutlarına aşina olmayı gerektirdiği için proje geçmişini dağıtma potansiyeline rağmen kullanımı zor

Git nesnelerini değiştirmeyen metadata

  • Git notes, Git’in takip ettiği nesnelere ayrı metadata kaydetme özelliğidir
    • Hedef yalnızca commit’ler değil, blob ve tree nesnelerini de kapsar
    • Nesnenin kendisini değiştirmeden, ayrı bir ad alanına bilgi ekler
  • Geçmişe girmiş commit mesajlarını güvenli biçimde sonradan düzeltmek genelde zordur; ancak notes kullanılırsa eski commit’lere de yeni bilgi eklenebilir
    • Örneğin aşağıdaki gibi git notes add -m ile bir not eklenebilir 
      git notes add -m 'Acked-by: <tyler@tylercipriani.com>'
    • Ardından git log içinde ilgili commit’in altında Notes: bloğu olarak görünür
  • Scott Chacon, 2010’da GitHub.blog’da notes özelliğinin, diğer geliştiricilerle konuşmaktan çok ticket·build sistemi gibi otomasyon kayıtlarını eklemek için daha uygun olduğunu söylemişti

Gerçek kullanım ve tıkanılan noktalar

  • Git projesi, her commit’i e-posta listesi tartışmalarına bağlamak için notes kullanıyor
  • notes; commit veya branch bazlı çalışma süresi takibi, git log içine inceleme·test bilgisi ekleme ve tamamen dağıtık kod incelemesi gibi amaçlarla da kullanılabiliyor
  • Gerrit’in reviewnotes eklentisi, kod inceleme metadata’sının Git içinde çevrimdışı görüntülenmesini sağlıyor
    • notes’u çekmek ve göstermek için komutlar şöyle 
      git fetch origin refs/notes/review:refs/notes/review
git log --show-notes=review
    • Gösterilen bilgiler arasında Verified+1, Verified+2, Code-Review+2, Submitted-by, Submitted-at, Reviewed-on, Project, Branch yer alıyor
  • Google’ın git-appraise aracı, git notes üzerine kurulu “fully distributed code review” sistemidir
    • GitHub ve GitLab gibi code forge platformlarından bağımsız çalışır
    • Değişiklik için inceleme isteği açma, değişikliğe yorum yapma, inceleme ve birleştirme işlemleri yerel bilgisayarda yapılabilir
    • Bir web arayüzü de içerir
  • En büyük zayıflık kullanılabilirlik
    • GitHub, 2014’te commit notes gösterimini durdurdu
    • Commit notes için otomatik fetch ve git log gösterimi, gitconfig ayarlarıyla bir ölçüde kolaylaştırılabilir 
      git config --add \
remote.origin.fetch \
'+refs/notes/*:refs/notes/*'

git config \
notes.displayRef \
'refs/notes/*'
    • Blob veya tree nesnelerine notes kaydetmek için Git’in plumbing komutlarına aşina olmak gerekir
  • Git, kod geçmişini dağıtır; ancak Git deposunun değerinin büyük kısmı GitHub gibi forge platformlarının içinde kilitli kalır
    • git notes, yalnızca kodu değil, projenin tüm geçmişini de dağıtmanın bir yolu olabilir

İlgili okumalar

1 yorum

 
GN⁺ 2025-06-23
Hacker News yorumları

  • Pek bilinmeyen bir başka özellik de git trailers: https://alchemists.io/articles/git_trailers
    Commit oluştururken eklenebilen anahtar-değer yapısında veriler; bazı sistemler bunu metadata iliştirmek için kullanıyor. Örneğin Gerrit, Change-Id eklemek için bu özelliği kullanıyor

    • Diğer sistemlerdeki benzer bir özellik olarak PostgreSQL COMMENT var: https://www.postgresql.org/docs/17/sql-comment.html
      PostgreSQL’deki çeşitli veritabanı nesnelerine metin iliştirmenizi sağlar. PostgreSQL’de de düzenlenebilir, yapılandırılmış anahtar-değer biçiminde veritabanı nesnesi metadata’sı özelliği olsa güzel olurdu
    • GitHub’ın [skip ci] koymaya alternatif olarak git trailers kullandığını yakın zamanda öğrendim; muhtemelen commit mesajını tüketen alt sistemlerde daha kolay kaldırabilmek içindir: https://docs.github.com/en/actions/managing-workflow-runs-an...
      Neden son trailer olmasını zorunlu tuttuğunu bilmiyorum; regex yüzünden olabilir
    • Kendi branch’imdeki commit’ler arasında unit test çalıştırdıklarımı işaretlemek için git notes kullanmıştım; script de bu commit’leri atlıyordu
      Açık kaynak upstream ile çalışırken branch’i git rebase -i ile kusursuzca düzenlemek istediğimde işe yarıyordu. Şimdi bu bilgiyi git trailers’a koymak daha iyi gibi görünüyor. Change-Id konusunda ise Git’in kendisinde böyle tanımlayıcılar olsa araçlar da anlayabileceği için iyi olurdu. Commit’i commit mesajıyla tanımlamak, özellikle MR’da mesaj değiştirilebildiğinde kırılgan. Commit ID commit’i benzersiz biçimde tanımlar ama aynı değişiklik başka bir commit’in üzerine taşınabiliyorsa kullanışlı bir tanımlayıcı değildir. Öte yandan trailers gerçek commit’in bir parçası, notes ise değil; bu yüzden benim kullanımım için iyi bir alternatif olmazdı
    • İlginç, bu özelliği bilmiyordum. conventional commits’i seviyorum; trailers böyle metadata eklemek için daha iyi bir yol gibi görünüyor
      Commit mesajına elle koymakla --trailer bayrağını kullanmanın işlevsel olarak aynı olup olmadığını merak ediyorum
    • GOOG’da çalışırken kullandığım Gerrit’i gerçekten özlüyorum ama 2020’ler itibarıyla dağıtım hikâyesi pek iyi değil
      Yerelde bir instance ayağa kaldırıp GitHub’da barındırılan bir repo ile entegre etmeye çalıştım, sadece hayal kırıklığı oldu. Commit’ler arasında değişiklik takibi vb. şeyleri GitHub’dan daha iyi halleden, daha aktif geliştirilen ve GitHub entegrasyonu da daha dostane olan bir alternatif var mı merak ediyorum. GitHub’ın code review araçlarından gerçekten nefret ediyorum

  • Forgejo da bu yıl ocakta çıkan 10. sürümden beri destekliyor: https://forgejo.org/2025-01-release-v10-0/#new-features
    https://codeberg.org/forgejo/forgejo/pulls/4753

  • Gerçekten harika görünüyor ama amend veya rebase gibi pratikte commit’i değiştirilmiş bir kopyasıyla değiştiren history rewrite özellikleriyle notes’un nasıl birlikte çalıştığını merak ediyorum
    Notes belirli bir commit, tree veya blob ID’sine iliştiriliyor gibi geliyor. git rebase vb.nin notes’u yeni commit’e kopyalayacak kadar akıllı olup olmadığını, yoksa basitçe kaybolup kaybolmadığını merak ediyorum. Interactive rebase’de birden çok commit’i tek commit’te squash edince ne oluyor, o da soru işareti. Blob’lara ve tree’lere notes iliştirmek de aynı soruna sahip gibi görünüyor. Depodaki bir dosyaya ya da dizine metadata iliştiriyormuşsunuz gibi hissettiriyor ama aslında belirli içeriğe iliştiriyorsunuz. Örneğin "Hello world!" dizesini içeren bir blob’a note iliştirirseniz Git bu note’u o içeriğe sahip tüm dosyalara bağlar mı? Ayrıca bir dosyayı "Hello, world!" olarak değiştirirseniz notes’u kaybeder misiniz?

    • Bu yapılandırılabilir. Varsayılan olarak amend ve rebase işlemleri notes’u ileriye kopyalar. notes.rewrite öğesine git-config(1) içinde bakabilirsiniz

  • Git’i herhalde yaklaşık 10 yıldır kullanıyorum ama git notes olduğunu bilmiyordum. Harika
    “Tüm forge’lar code review metadata’sını Git içinde offline kullanılabilir hale getirsin” talebi, GitHub gibi ticari forge’larda pek karşılık bulmayacak gibi. Senin de dediğin gibi, Git deposunun değerinin büyük kısmı GitHub gibi forge’larda kilitli olduğu için. Kâr amaçlı şirketler genellikle kendi katma değerlerini genelleştirme konusunda hevesli olmaz. GitHub’ı suçlamak istemiyorum; harika bir hizmet ve çok cömert bir ücretsiz katman sunuyorlar, ayrıca taşınmak isterseniz API ile tüm verileri çıkarmanıza izin vermeleri açısından iyi iş çıkarıyorlar. Bu sadece ticari işletmenin doğası

    • Önce bu özelliği farklılaştırıcı unsur olarak öne çıkaran yeni bir servis başlatmak gerekir; o zaman rakipler de yetişmek için bu özelliği yeniden ekleyebilir

  • Git notes, yalnızca commit zaten oluşturulup başkalarına göründükten sonra sık sık metin eklemeniz gerektiğinde harika
    Acked-By ve e-posta listesi tartışma bağlantısı örnekleri pek iyi örnekler gibi değil. İkisi de commit oluşturulurken zaten biliniyor olma ihtimali yüksek şeyler. Git commit mesajlarının pratikte neredeyse uzunluk sınırı yok; dolayısıyla forge üzerinde commit hakkında yapılan tartışmayı doğrudan commit mesajının içine kopyalayabilirsiniz. Bence daha iyi bir örnek, sonradan geri alınmış bir commit’e git note eklemek olur

    • Yaygın bir hata modu, commit mesajının aslında düzeltilmemiş bir hatayı düzelttiğini kendinden emin biçimde ilan etmesidir. Sonra da düzeltmenin yarattığı zincirleme hataları tek bir hataya bağlar
      Tuhaf olan ben olabilirim ama kodun en başta neden yazıldığını hatırlamaya çalışırken yorumlara ya da annotate’e düzgün bakmayan çok fazla iş arkadaşı gördüm. Doğrudan değiştirip sorunun kendilerine bağlanmamasını umuyorlar. Ama sadece hata düzeltmesini bekleyen öfkeli bir müşteriyle uğraşıp çok geçmeden aynı hatanın geri geldiğini görünce hata düzeltirken daha dikkatli olabilirsiniz. Birden fazla hatayı aynı anda düzeltmek çoğu zaman refactoring gerektirir; refactoring de yeni özellik fırsatları veya performans iyileştirmeleri açabilir
    • Bir commit hakkındaki tartışma, yani review ve commit onayı (Ack), commit oluşturulmadan önce gerçekleşemez
      Sonradan geri alınmış bir commit’i işaretlemek için commit mesajı daha iyidir. Bir dosyada blame çalıştırırsanız o dosyanın en son değişikliği görünür; bir commit başka bir commit’in değişikliğini geri aldıysa blame’de daha yeni olan revert commit’i görünür
    • Commit oluşturulduktan sonra da tartışma devam edebilir

  • Bu bilgi eksikliği değil, bir UI sorunu. GitHub UI notes’u gösterseydi kullanım hemen çok daha fazla artardı

    • GitHub’ın bunu desteklemesini isterdim

  • “Git’in en havalı ama sevilmeyen özelliği” çok. Örneğin bisect, pickaxe, reflog, range-diff, archive, annotated tags vb.
    Pek çok kişinin Git’i süslü bir Google Drive gibi görmesi ve bu özelliklerin sık sık unutulması üzücü

    • Git notes, özellik takibi için zaten daha üst düzey bir proje yönetimi aracı gerektiğinden mükerrer. Yol haritası, özellik hiyerarşisi, teknik olmayan ayrıntılar gerekir; büyük bir issue tracker veya Jira’yı düşünün
      Yine de bence sorun değil. Unix felsefesi tek bir şeye odaklanıp onu iyi yapmaktır
    • Çoğu durumda bu özellikler aslında o kadar kullanışlı değildir; işin yükünü taşıyan temel aracın etrafındaki süslemelere daha yakındır
    • Listelenen özelliklerin hepsini bileceğimi sanıyordum ama pickaxe beni hazırlıksız yakaladı. Fazla kendime güvenmemem gerek

  • LibreOffice projesinde Apache OpenOffice deposundaki her commit’i izlemek için Git notes kullanılmıştı
    O depoyu LibreOffice Git deposunda bir branch olarak mirror ederken, her commit’in alakasız bir değişiklik olup olmadığını — örneğin LibreOffice’in uzun zaman önce daha iyisiyle değiştirdiği build system değişikliği mi, LibreOffice’te zaten bulunan bir değişikliğin tekrarı mı, yoksa nadiren LibreOffice’e kabul edilmişse hangi commit ile cherry-pick edildiğini — kaydediyorlardı. Hâlâ https://cgit.freedesktop.org/libreoffice/core/log/?h=aoo/tru... adresinde kendiniz görebilirsiniz; bu Git frontend’i hâlâ notes’u gösteriyor. Birkaç yıldır bu değişiklik takibini durdurdular; muhtemelen Apache OpenOffice’in değişiklik hızı çok yavaşladığı ve cherry-pick edilecek az sayıdaki değişiklikten elde edilecek fayda pek kalmadığı için

  • En havalı ama sevilmeyen özellikten ziyade, tüm şirketi yalnızca geliştiricilerle işleten bir ekip gibi çok belirli durumlarda havalı olabilecek bir gimmick özellike daha yakın
    Gerekli olan şey commit mesajına girer; ayrı bir sistemdeki ticket’a referans vermek bug değil, feature’dır. Çünkü JIRA veya başka sistemler geliştirici olmayanlarla iletişim kurmak için kullanılır. Örneğin bir business analyst’in koda veya depoya hiç erişimi yoktur; destek ekibinin de depoya ve koda erişimi yoktur. Geliştirici olmayanların notes’u görüp düzenleyebileceği bir frontend yapılabilir ama yine de pek anlamı olmaz. BA veya destek ekipleri belirli bir commit ile ilgilenmez; bir özellik tek bir commit’e tam oturabilir ama genelde öyle olmaz. Birden fazla depo kullanıyorsanız ve tek bir özellik birden fazla servise yayılıyorsa git notes epey işe yaramaz hâle gelir; sonunda harici bir sisteme referans gerekir

    • Business analyst veya destek personeline kod ve depo erişimi verilmemesi bana daha tuhaf geliyor. Kendi ürününüzü black box gibi ele almanın ne faydası var?
      Ama ana akım olan bu. Bazen aynı monorepo’yu paylaştığımız başka bir ekibin analisti, tek satır kodla hemen yanıtlanabilecek bir soruyu bana soruyor. Üstelik o analist teknik sayılır ve SQL de biliyor; kodumuz da oldukça idiomatik ve üst düzey yazılmış. Yine de kültür, içsel verimsizlik yüzünden ölmeden kendi kendini değiştiremiyor
    • Commit mesajına ait olmayan ama ilgili çok sayıda commit dışı veri var. Testlerin geçip geçmediği[1], manuel test kayıtları, code review’in iterasyonları, 6 aydan eski sorunlu bir commit’i araştırırken bırakılan notlar gibi
      [^1] https://news.ycombinator.com/item?id=44348438

  • GitLab’in notes desteği için açılmış 9 yıllık özellik isteği yakın zamanda kapatıldı: https://gitlab.com/gitlab-org/gitlab/-/issues/15029
    Ne yazık ki okumak için giriş yapmak gerekiyor, ama herhangi bir gitlab.com hesabı yeterli olmalı

    • Daha tamamlanmış bir öneri içeren başka bir issue da var: https://gitlab.com/gitlab-org/gitlab/-/issues/216351
    • Merak edenler için: tamamlandığı için değil, ilgisiz bırakıldığı için kapatılmış: “Odak noktamız şu anda bu alan olmadığı için bu özellik isteğini kapatıyoruz”