Git Notes: Fitur Git yang Paling Keren dan Paling Kurang Dicintai (2022)

• Git notes adalah alat yang kuat untuk menambahkan metadata ke commit dan objek lainnya
• Fitur ini memungkinkan menyimpan informasi pelengkap ketika pesan commit tidak bisa diubah
• Dapat digunakan untuk menyimpan berbagai informasi seperti riwayat code review atau hasil pengujian
• Bahkan bisa dipakai untuk membangun sistem code review terdistribusi, tetapi kegunaan dan tingkat pengenalannya rendah
• Karena dukungannya minim, termasuk dinonaktifkan di GitHub, adopsi sehari-harinya rendah

---

Apa itu Git notes

• Git notes adalah fitur di git yang memungkinkan penambahan metadata ke objek apa pun yang dilacak git (commit, blob, tree)
• Pada umumnya, pesan commit yang sudah tercatat tidak bisa diubah, tetapi dengan git notes informasi baru dapat ditambahkan tanpa mengubah isi commit
• Sebagai contoh, notes dapat ditambahkan ke commit seperti berikut
  • git notes add -m 'Acked-by: <이메일>'
• Notes akan ditampilkan bersama di git log sebagai bagian terpisah

Contoh penggunaan nyata

• Bahkan proyek git sendiri memanfaatkan git notes untuk menghubungkan commit dengan thread diskusi di mailing list
• Contoh penggunaan nyata notes mencakup hal-hal berikut
  • Pelacakan waktu kerja per commit atau per branch
  • Penyimpanan log code review dan hasil pengujian
  • Perancangan sistem code review yang sepenuhnya terdistribusi

Menyimpan code review dan hasil pengujian

• Semakin banyak kasus di mana code forge atau sistem review mendukung penyimpanan metadata code review secara offline, yaitu langsung di git itu sendiri
• Plugin reviewnotes milik Gerrit menampilkan pelaku review dan riwayat eksekusi pengujian sebagai notes di git log
  • Pengguna dapat memeriksa riwayat peninjauan kode secara lokal tanpa perlu membuka browser terpisah

Sistem code review terdistribusi

• Ada contoh implementasi code review terdistribusi menggunakan git notes, seperti git-appraise yang dikembangkan di Google
• git-appraise mencatat seluruh proses seperti permintaan code review, komentar atas perubahan, dan merge setelah review ke dalam git notes, serta bekerja secara independen tanpa bergantung pada layanan hosting kode online
• Semua kolaborasi dapat dilakukan di lingkungan lokal, dan bahkan menyediakan antarmuka web

Kegunaan dan pengenalan yang rendah

• Git notes hampir tidak digunakan karena antarmukanya kurang nyaman dan tidak intuitif bagi pengguna umum
• GitHub berhenti menampilkan commit notes sejak 2014, sehingga kesempatan untuk memakainya semakin berkurang
• Pengelolaan notes untuk commit bisa dibuat agak lebih mudah lewat pengaturan git, tetapi untuk menempelkan notes pada objek blob atau tree diperlukan pemahaman tambahan tentang struktur internal git (plumbing)
• Akibatnya, git notes tetap menjadi fitur yang cenderung digemari kalangan penggemar saja dan sangat rendah tingkat pengenalannya

Kemandirian dari forge terbuka

• Git sendiri dapat mendukung version control terdistribusi dan code review, tetapi banyak nilai tambah seperti riwayat review cenderung bergantung pada layanan hosting seperti GitHub
• Dengan memanfaatkan fitur Git notes, terbuka jalan untuk menyimpan dan mendistribusikan bukan hanya sejarah perubahan kode, tetapi juga seluruh riwayat proyek secara terdistribusi
• Ini memiliki makna penting bagi ekosistem pengembangan yang sepenuhnya terdistribusi dan pelestarian catatan

[GN⁺]

Komentar Hacker News

• Berbagi info bahwa ada fitur yang kurang dikenal bernama git trailers; trailer memungkinkan penyisipan metadata berbentuk key-value saat membuat commit. Ini digunakan di Gerrit untuk menambahkan Change-Id. Tautan artikel terkait

  • Berbagi info bahwa PostgreSQL memiliki fitur serupa bernama COMMENT; COMMENT dapat menambahkan teks ke objek database. Ada harapan PostgreSQL juga menyediakan fitur untuk mengedit metadata terstruktur berbentuk key-value. Tautan dokumentasi terkait

  • Berbagi pengalaman menggunakan git notes saat mengerjakan upstream open source untuk menandai commit yang unit test-nya sudah selesai; ini berguna saat merapikan branch dengan git rebase -i, tetapi trailer sekarang tampak seperti cara yang lebih baik. Jika fitur seperti Change-Id dimasukkan ke git itu sendiri, alat-alat sepertinya bisa memahaminya dengan lebih baik. Membedakan commit lewat pesan commit agak rapuh; commit id memang bagus karena unik, tetapi jika perubahan yang sama dipindahkan ke atas commit lain, kegunaannya sebagai pengenal menurun. Koreksi: trailer adalah bagian dari commit, jadi tidak bisa sepenuhnya menggantikan notes

  • Baru tahu bahwa GitHub belakangan memakai trailer terpisah alih-alih [skip ci], mungkin agar lebih mudah dipisahkan dari pesan commit. Tidak yakin mengapa GitHub hanya mensyaratkan trailer terakhir; dugaan saya mungkin karena pemrosesan regex. Tautan dokumentasi terkait

  • Baru pertama kali tahu soal trailer. Sebagai penggemar Conventional Commits, rasanya trailer lebih cocok untuk menambahkan metadata seperti ini. Penasaran apakah menambahkannya secara manual ke pesan commit dan memakai flag --trailer itu secara fungsional sama

  • Secara alami ingin terhubung dengan sistem pelacakan isu, tetapi menaruh itu di tempat seperti trailer terasa tidak efisien karena terlalu jauh dari issue tracker. Issue tracker cenderung mengikuti tren dan sering terlambat menambahkan berbagai fitur. Aturan yang memaksa nama branch yang diturunkan dari nama tiket harus dipakai sebagai judul PR terasa merepotkan. Ingin menghubungkan commit dan issue lewat metadata lain agar judul PR bisa lebih bermakna. Ini bukan hal yang mudah diubah, jadi jadinya cuma bahan keluhan di internet

• Berbagi info bahwa Forgejo mulai mendukung trailer sejak versi 10 yang dirilis Januari tahun ini catatan rilis pull request

• Penasaran soal interaksi antara git notes dan fitur penulisan ulang riwayat (amend, rebase, dll.); karena notes terhubung ke ID commit/tree/blob, apakah notes disalin atau hilang saat diganti dengan commit baru? Juga penasaran apa yang terjadi saat beberapa commit digabung lewat interactive rebase. Ada kesan bahwa notes menempel pada “isi” file/direktori, yang berbeda dari ekspektasi; misalnya jika sebuah note ditempel ke blob string "Hello world!", apakah note itu akan menempel ke semua file dengan isi yang sama, dan apakah notes akan hilang jika file berubah

  • Di git rebase dan lain-lain, penyalinan notes bisa diatur agar secara default memang disalin; lihat opsi notes.rewrite di git-config(1)

• Di tempat kerja saat ini aktif menggunakan git notes, dengan tujuan mengelola catatan code review internal tanpa membuat pesan commit jadi rumit atau harus membuat PR untuk semua perubahan. Mereka meninggalkan konteks pada branch, seperti tiket apa yang dipetakan ke tiap commit, batasan infrastruktur, atau untuk perbaikan, tautan ke thread insiden. Dengan menyimpan informasi ini di repo, jadi lebih mudah memahami mengapa satu baris berubah tanpa harus mencari di Slack atau Jira. Jika dipakai dalam skala besar, ini bisa jelas mengurangi kebutuhan akan UI platform. Ada pendapat bahwa reproducibility dibutuhkan bukan hanya untuk build tetapi juga untuk ‘intent’

  • Apakah informasi seperti ini sebaiknya masuk ke pesan commit saja, ataukah tujuannya juga untuk menautkan arah masa depan seperti “commit ini menyebabkan bug #123”

• git notes benar-benar berguna hanya saat informasi tambahan dibutuhkan setelah commit. Contoh seperti Acked-By atau tautan diskusi mailing list adalah informasi yang sudah diketahui saat commit dibuat, jadi bisa langsung ditambahkan ke pesan commit. Justru keunggulan nyata git note menurut saya adalah untuk menambahkan penjelasan tambahan belakangan, misalnya pada commit yang kemudian di-revert

  • Sering kali pesan commit mengklaim sudah memperbaiki bug padahal sebenarnya belum, sehingga memicu bug susulan, dan rekan kerja kerap mengabaikan niat awal penulis lalu berlalu begitu saja. Setelah mengalami pelanggan marah dan bug yang muncul lagi, terasa perlu lebih berhati-hati saat menyebut sesuatu sebagai bug fix. Kadang satu perubahan memperbaiki beberapa bug sekaligus, atau refactor juga membuka peluang untuk peningkatan performa maupun fitur baru

  • Acked-By, review, dan diskusi memang sering baru berlanjut setelah commit dibuat; pada saat commit dilakukan, itu belum diketahui. Untuk kasus commit revert justru lebih berguna jika ditambahkan ke pesan commit, karena fitur blame menampilkan perubahan terbaru sehingga commit yang di-revert pun secara alami tetap bisa dilacak

  • Sering kali diskusi berlanjut bahkan setelah commit dibuat

• Menurut saya ini poin menarik untuk dieksplorasi, terutama demi memberi konteks tambahan kepada code agent lewat fitur notes

• Ini bukan masalah kurang pengetahuan, melainkan masalah UI; kalau UI GitHub menampilkan notes dengan baik, orang akan jauh lebih banyak memakainya

  • Semoga GitHub mendukung notes

• Git punya banyak ‘fitur paling keren yang kurang dicintai’ seperti bisect, pickaxe, reflog, range-diff, archive, annotated tags, dan lain-lain, tetapi kebanyakan orang hanya menganggapnya seperti Google Drive sehingga tidak memakainya dengan baik

  • git notes terasa duplikatif karena konteks nonteknis seperti feature atau roadmap toh tetap dilacak lewat alat manajemen proyek terpisah, misalnya Jira. Sesuai filosofi Unix, masing-masing alat sebaiknya fokus pada perannya sendiri

  • Baru pertama kali mendengar fitur pickaxe; ternyata di luar dugaan. Sepertinya tidak boleh terlalu percaya diri

  • Fitur-fitur yang tampak dekoratif seperti ini sering kali sebenarnya tidak terlalu berguna; dianggap lebih sebagai trik sampingan di sekitar hal yang esensial

• Ada pendapat bahwa git notes bukan benar-benar fitur ‘keren’ yang kurang disukai, melainkan hanya berguna dalam situasi tertentu yang sangat terbatas. Pola di mana semua informasi penting dimasukkan ke pesan commit lalu dirujuk dari sistem lain, misalnya JIRA, justru punya kelebihan. Sistem seperti JIRA juga berperan sebagai kanal komunikasi dengan business analyst atau staf support yang bukan developer. Masuk akal juga jika orang non-developer tidak punya akses ke repo dan kode. Dalam situasi yang menangani banyak layanan/repo sekaligus, referensi feature lewat notes semacam itu secara realistis tidak mungkin; harus terintegrasi dengan sistem eksternal

  • Menunjukkan bahwa business analyst yang tidak bisa mengakses kode atau repo itu tidak efisien; kenyataannya sering ditanya berulang soal hal-hal yang sebenarnya bisa dipahami hanya dengan melihat satu baris kode. Ada juga analyst yang punya kemampuan teknis, tetapi budaya seperti ini sulit diubah

• Pertama kali tahu notes sekitar tahun 2020 lewat halaman man. Pada dasarnya notes hanya berlaku untuk repo lokal, jadi belum pernah benar-benar memakainya. Agar bisa digunakan dalam tim, pushing/fetching harus diatur terpisah dan diputuskan bersama, tetapi tim saya tidak mengadopsinya