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

 (tylercipriani.com)
3 poin oleh GN⁺ 2025-06-23 | 1 komentar | Bagikan ke WhatsApp
  • Git notes adalah fitur untuk menempelkan metadata ke objek Git dalam namespace terpisah tanpa mengubah objek Git itu sendiri, tetapi tidak banyak digunakan karena kegunaan yang rendah dan adopsi yang terbatas
  • Tanpa perlu memperbaiki pesan commit lama, kita bisa menambahkan informasi baru, sehingga sangat cocok untuk catatan yang ditinggalkan sistem otomatis seperti informasi review, build, dan tiket
  • Proyek Git dan Gerrit benar-benar memanfaatkan notes agar diskusi mailing list, hasil pengujian, dan informasi reviewer per commit bisa dilihat di git log
  • git-appraise dari Google mengimplementasikan code review terdistribusi di atas git notes, sehingga permintaan review, komentar, review, dan merge bisa dilakukan secara lokal
  • Pada 2014 GitHub berhenti menampilkan commit notes, dan notes untuk blob maupun tree sulit digunakan karena harus terbiasa dengan perintah internal Git, meski ada potensi untuk mendistribusikan riwayat proyek

Metadata tanpa mengubah objek Git

  • Git notes adalah fitur untuk menyimpan metadata terpisah pada objek yang dilacak Git
    • Targetnya bukan hanya commit, tetapi juga blob dan tree
    • Informasi ditempelkan dalam namespace terpisah tanpa memodifikasi objek itu sendiri
  • Pesan commit yang sudah masuk ke riwayat biasanya sulit diperbaiki dengan aman, tetapi dengan notes kita bisa menambahkan informasi baru bahkan ke commit lama
    • Memo dapat ditambahkan dengan git notes add -m seperti berikut 
      git notes add -m 'Acked-by: <tyler@tylercipriani.com>'
    • Setelah itu akan ditampilkan sebagai blok Notes: di bawah commit terkait dalam git log
  • Scott Chacon dalam GitHub.blog pada 2010 melihat notes sebagai fitur yang lebih cocok untuk menempelkan catatan otomatis seperti sistem tiket dan build daripada percakapan dengan developer lain

Pemakaian nyata dan titik hambatannya

  • Proyek Git menggunakan notes untuk menghubungkan tiap commit dengan diskusi mailing list
    • Pada commit contoh, Notes (amlog) berisi Message-Id, dan nilai ini terhubung ke thread diskusi patch
  • notes juga digunakan untuk pelacakan waktu kerja per commit atau branch, menambahkan informasi review dan pengujian ke git log, serta code review yang sepenuhnya terdistribusi
  • Plugin reviewnotes milik Gerrit memungkinkan metadata code review dilihat secara offline di dalam Git
    • Perintah untuk mengambil dan menampilkan notes adalah sebagai berikut 
      git fetch origin refs/notes/review:refs/notes/review
git log --show-notes=review
    • Informasi yang ditampilkan mencakup Verified+1, Verified+2, Code-Review+2, Submitted-by, Submitted-at, Reviewed-on, Project, Branch, dan lainnya
  • git-appraise dari Google adalah sistem “fully distributed code review” yang dibangun di atas git notes
    • Berjalan secara independen dari code forge seperti GitHub dan GitLab
    • Permintaan review perubahan, komentar pada perubahan, review, dan merge dapat dilakukan dari komputer lokal
    • Juga menyertakan antarmuka web
  • Kelemahan terbesarnya adalah kegunaan
    • Pada 2014 GitHub berhenti menampilkan commit notes
    • Untuk commit notes, auto-fetch dan tampilan di git log bisa dibuat agak lebih mudah melalui pengaturan gitconfig 
      git config --add \
remote.origin.fetch \
'+refs/notes/*:refs/notes/*'

git config \
notes.displayRef \
'refs/notes/*'
    • Untuk menyimpan notes pada blob atau tree, pengguna harus terbiasa dengan plumbing Git
  • Git mendistribusikan riwayat kode, tetapi banyak nilai dari repositori Git terkunci di dalam forge seperti GitHub
    • git notes bisa menjadi jalur untuk mendistribusikan bukan hanya kode, tetapi juga seluruh riwayat proyek

Bacaan terkait

1 komentar

 
GN⁺ 2025-06-23
Opini Hacker News

  • Fitur lain yang kurang dikenal adalah git trailers: https://alchemists.io/articles/git_trailers
    Ini adalah data terstruktur key-value yang bisa disertakan saat membuat commit, dan sebagian sistem menggunakannya untuk melampirkan metadata. Misalnya Gerrit memakai fitur ini untuk menambahkan Change-Id

    • Fitur serupa di sistem lain adalah PostgreSQL COMMENT: https://www.postgresql.org/docs/17/sql-comment.html
      Fitur ini memungkinkan teks ditempelkan ke berbagai objek database PostgreSQL. Akan bagus kalau PostgreSQL juga punya fitur metadata objek database berbentuk key-value terstruktur yang bisa diedit
    • Baru-baru ini saya tahu GitHub memakai git trailers sebagai alternatif untuk memasukkan [skip ci], mungkin agar lebih mudah dihapus oleh subsistem yang mengonsumsi pesan commit: https://docs.github.com/en/actions/managing-workflow-runs-an...
      Saya tidak tahu kenapa dipaksa harus menjadi trailer terakhir; mungkin karena regex
    • Saya pernah memakai git notes untuk menandai commit di branch saya yang sudah menjalankan unit test, lalu membuat skrip melewati commit-commit seperti itu
      Itu berguna ketika bekerja dengan upstream open source dan ingin merapikan branch secara sempurna dengan git rebase -i. Sekarang rasanya informasi itu lebih baik dimasukkan ke git trailers. Soal Change-Id, akan bagus kalau Git sendiri punya identifier semacam ini agar tooling juga bisa memahaminya. Mengidentifikasi commit lewat pesan commit itu rapuh, terutama di MR ketika pesan bisa diubah. Commit ID memang mengidentifikasi commit secara unik, tetapi bukan identifier yang berguna ketika perubahan yang sama bisa dipindahkan ke atas commit lain. Namun trailers adalah bagian dari commit yang sebenarnya sedangkan notes bukan, jadi untuk penggunaan saya dulu, trailers bukan pengganti yang baik
    • Menarik, saya tidak tahu fitur ini. Saya suka conventional commits, dan trailers terlihat seperti cara yang lebih baik untuk menambahkan metadata semacam itu
      Saya penasaran apakah memasukkannya secara manual ke pesan commit dan memakai flag --trailer secara fungsional sama
    • Saya sangat merindukan Gerrit yang saya pakai saat bekerja di GOOG, tetapi dari sudut pandang era 2020-an, urusan deployment-nya cukup buruk
      Saya pernah mencoba menjalankan instance lokal dan mengintegrasikannya dengan repository yang di-host di GitHub, tetapi hanya berujung frustrasi. Saya penasaran apakah ada alternatif yang menangani pelacakan perubahan lintas commit dan hal-hal lain lebih baik daripada GitHub, sekaligus lebih aktif dikembangkan dan ramah integrasi GitHub. Saya benar-benar tidak suka alat code review GitHub

  • Forgejo juga mendukungnya sejak versi 10 yang dirilis Januari tahun ini: https://forgejo.org/2025-01-release-v10-0/#new-features
    https://codeberg.org/forgejo/forgejo/pulls/4753

  • Kelihatannya sangat keren, tetapi saya penasaran bagaimana notes bekerja bersama fitur penulisan ulang history seperti amend atau rebase, yang pada praktiknya mengganti commit dengan salinan yang dimodifikasi
    Notes terdengar seperti ditempelkan ke commit, tree, atau blob ID tertentu. Saya penasaran apakah git rebase dan semacamnya cukup pintar untuk menyalin notes ke commit baru, atau apakah notes itu hilang begitu saja. Saya juga bertanya-tanya apa yang terjadi jika beberapa commit di-squash menjadi satu dalam interactive rebase. Menempelkan notes ke blob dan tree juga terlihat punya masalah yang sama. Rasanya seperti menempelkan metadata ke file atau direktori di repository, tetapi sebenarnya ditempelkan ke konten tertentu. Misalnya jika saya menempelkan note ke blob berisi string "Hello world!", apakah Git akan mengaitkan note itu ke semua file yang memiliki konten tersebut? Lalu jika satu file diubah menjadi "Hello, world!", apakah notes-nya akan hilang?

    • Ini bisa dikonfigurasi. Secara default, operasi amend dan rebase menyalin notes ke depan. Untuk item notes.rewrite, lihat git-config(1)

  • Saya mungkin sudah memakai Git sekitar 10 tahun, tetapi tidak tahu git notes ada. Keren
    Permintaan “biarkan semua forge membuat metadata code review tersedia offline di dalam Git” tampaknya tidak akan terlalu mempan untuk forge komersial seperti GitHub. Seperti yang sudah dikatakan, banyak nilai dari repository Git terkunci di forge seperti GitHub. Perusahaan berorientasi laba biasanya tidak terlalu bersemangat menjadikan nilai tambah mereka sebagai sesuatu yang generik. Saya tidak bermaksud menyalahkan GitHub; menurut saya mereka melakukan hal yang baik dengan menyediakan layanan bagus dan free tier yang sangat murah hati, serta memungkinkan semua data diekstrak lewat API kalau kita ingin pindah. Itu hanya sifat dasar operasi komersial

    • Harus ada layanan baru yang lebih dulu menjadikan fitur itu sebagai pembeda, lalu para pesaing mungkin akan menambahkan kembali fitur tersebut supaya bisa mengejar

  • Git notes hanya keren ketika Anda sering perlu menambahkan teks setelah commit sudah dibuat dan terlihat oleh orang lain
    Contoh Acked-By dan tautan diskusi milis tampaknya bukan contoh yang bagus. Keduanya kemungkinan besar sudah diketahui saat membuat commit. Pesan commit Git pada dasarnya hampir tidak punya batas panjang, jadi diskusi terkait commit yang terjadi di forge bisa saja disalin apa adanya ke pesan commit itu sendiri. Contoh yang lebih baik menurut saya adalah menambahkan git note pada commit yang kemudian di-revert

    • Mode kegagalan yang umum adalah pesan commit dengan percaya diri menyatakan telah memperbaiki bug yang sebenarnya belum diperbaiki. Lalu bug-bug berantai yang ditimbulkan oleh perbaikan itu dihubungkan ke satu bug
      Mungkin saya yang aneh, tetapi saya sudah melihat terlalu banyak rekan kerja yang tidak benar-benar melihat komentar atau annotate untuk mengingat kenapa kode itu ditulis sejak awal. Mereka sekadar langsung mengubahnya dan berharap masalahnya tidak terhubung ke mereka. Namun setelah berhadapan dengan pelanggan marah yang menunggu perbaikan bug, lalu tak lama kemudian mengalami bug itu masuk lagi, orang bisa menjadi lebih hati-hati terhadap perbaikan bug. Untuk memperbaiki beberapa bug sekaligus, sering kali dibutuhkan refactoring, dan refactoring juga bisa membuka peluang fitur baru atau peningkatan performa
    • Diskusi tentang commit, yaitu review dan persetujuan commit (Ack), tidak bisa terjadi sebelum commit dibuat
      Jika tujuannya meninggalkan penanda pada commit yang kemudian di-revert, pesan commit lebih baik. Saat melakukan blame pada file, Anda melihat perubahan terbaru pada file itu, dan jika suatu commit me-revert perubahan dari commit lain, commit revert yang lebih baru akan muncul di blame
    • Diskusi bisa terus berlanjut bahkan setelah commit dibuat

  • Ini bukan kurangnya pengetahuan, melainkan masalah UI. Jika UI GitHub menampilkan notes, penggunaannya akan langsung meningkat jauh

    • Saya berharap GitHub mendukung ini

  • Ada banyak “fitur Git yang paling keren tetapi kurang dicintai”. Misalnya bisect, pickaxe, reflog, range-diff, archive, annotated tags, dan sebagainya
    Sayang sekali banyak orang menganggap Git hanya semacam Google Drive yang lebih mewah, sehingga fitur-fitur seperti ini sering terlupakan

    • Git notes bagaimanapun juga redundan karena untuk pelacakan fitur diperlukan alat manajemen proyek pada tingkat yang lebih tinggi. Anda membutuhkan roadmap, hierarki fitur, detail nonteknis; bayangkan tracker besar atau Jira
      Namun menurut saya itu tidak masalah. Filosofi Unix adalah fokus pada satu hal dan melakukannya dengan baik
    • Dalam banyak kasus, fitur-fitur seperti itu sebenarnya tidak terlalu berguna, dan lebih mirip hiasan di sekitar alat inti yang berperan sebagai pekerja utama
    • Saya memperkirakan akan tahu semua fitur yang disebutkan, tetapi pickaxe menyergap saya. Sepertinya saya tidak boleh terlalu percaya diri

  • Proyek LibreOffice menggunakan Git notes untuk melacak setiap commit dari repositori Apache OpenOffice
    Saat repositori itu di-mirror sebagai branch di repositori Git LibreOffice, mereka mencatat apakah setiap commit merupakan perubahan yang tidak relevan, misalnya perubahan sistem build yang sudah lama diganti LibreOffice dengan sesuatu yang lebih baik, apakah perubahan itu duplikat dari perubahan yang sudah ada di LibreOffice, atau dalam kasus yang jarang terjadi apakah perubahan itu diterima ke LibreOffice dan di-cherry-pick sebagai commit yang mana. Anda masih bisa melihatnya langsung di https://cgit.freedesktop.org/libreoffice/core/log/?h=aoo/tru..., dan frontend Git ini masih menampilkan notes. Sejak beberapa tahun lalu, pelacakan perubahan seperti ini dihentikan, mungkin karena laju perubahan Apache OpenOffice menjadi sangat lambat sehingga manfaat dari men-cherry-pick segelintir perubahan yang ada tidak lagi seberapa

  • Alih-alih fitur paling keren tetapi kurang dicintai, ini lebih mirip fitur gimmick yang mungkin keren dalam kasus yang sangat spesifik, seperti tim yang menjalankan seluruh perusahaan hanya dengan developer
    Hal yang diperlukan masuk ke pesan commit, dan merujuk tiket di sistem terpisah bukanlah bug, melainkan fitur. Sebab JIRA atau sistem lain digunakan untuk berkomunikasi dengan non-developer. Misalnya, analis bisnis sama sekali tidak punya akses ke kode atau repositori, dan staf support juga tidak punya akses ke repositori maupun kode. Frontend yang memungkinkan non-developer melihat dan mengedit notes memang bisa dibuat, tetapi tetap tidak banyak artinya. BA, tim support, dan sebagainya tidak tertarik pada commit tertentu; satu fitur bisa saja pas dengan satu commit, tetapi biasanya tidak demikian. Jika memakai banyak repositori dan satu fitur mencakup beberapa layanan, git notes menjadi cukup tidak berguna, dan pada akhirnya tetap diperlukan referensi ke sistem eksternal

    • Rasanya justru aneh jika analis bisnis atau staf support tidak diberi akses ke kode dan repositori. Apa keuntungan memperlakukan produk sendiri seperti black box?
      Namun itulah arus utamanya. Kadang analis dari tim lain yang berbagi monorepo yang sama menanyakan kepada saya pertanyaan yang sebenarnya bisa langsung dijawab dengan satu baris kode. Analis itu cukup teknis dan juga tahu SQL, dan kode kami ditulis dengan sangat idiomatis serta pada level tinggi. Namun budaya tidak bisa berubah dengan sendirinya sampai mati oleh inefisiensi inherennya sendiri
    • Ada banyak data di luar commit yang relevan tetapi tidak cocok berada di pesan commit. Misalnya status lulus tes[1], catatan pengujian manual, proses iterasi code review, atau catatan yang ditinggalkan saat menggali commit bermasalah yang sudah berumur lebih dari 6 bulan
      [^1] https://news.ycombinator.com/item?id=44348438

  • Feature request berusia 9 tahun yang meminta dukungan notes di GitLab baru-baru ini ditutup: https://gitlab.com/gitlab-org/gitlab/-/issues/15029
    Sayangnya perlu login untuk membacanya, tetapi akun gitlab.com mana pun seharusnya bisa

    • Ada juga issue lain dengan proposal yang lebih matang: https://gitlab.com/gitlab-org/gitlab/-/issues/216351
    • Untuk yang penasaran, issue itu ditutup bukan karena sudah selesai, melainkan karena dibiarkan terbengkalai: “Kami menutup permintaan fitur ini karena fokus saat ini tidak berada di area ini”