Pesan Komit Git: Pemformatan 50/72

Tim Pope berpendapat untuk gaya pesan komit Git tertentu dalam posting blognya: http://www.tpope.net/node/106 .

Berikut ini ringkasan singkat dari apa yang dia rekomendasikan:

• Baris pertama adalah 50 karakter atau kurang.
• Kemudian baris kosong.
• Teks yang tersisa harus dibungkus dengan 72 karakter.

Posting blog-nya memberikan alasan untuk rekomendasi ini (yang akan saya sebut "format 50/72" untuk singkatnya):

• Dalam praktiknya, beberapa alat memperlakukan baris pertama sebagai baris subjek dan paragraf kedua sebagai badan (mirip dengan email).
• git log tidak menangani pembungkus, sehingga sulit dibaca jika garis terlalu panjang.
• git format-patch --stdout mengkonversi komit ke email - jadi bermain baik itu membantu jika komit Anda sudah dibungkus dengan baik.

Suatu hal yang ingin saya tambahkan bahwa saya pikir Tim akan setuju:

• Tindakan meringkas komit Anda adalah praktik yang baik secara inheren dalam sistem kontrol versi apa pun. Ini membantu orang lain (atau Anda nanti) menemukan komitmen yang relevan lebih cepat.

Jadi, saya punya beberapa sudut untuk pertanyaan saya:

• Apa potongan (kira-kira) dari "pemimpin pemikiran" atau "pengguna berpengalaman" dari Git merangkul gaya format 50/72? Saya menanyakan hal ini karena kadang-kadang pengguna yang lebih baru tidak tahu atau tidak peduli dengan praktik komunitas.
• Bagi mereka yang tidak menggunakan format ini, apakah ada alasan prinsip untuk menggunakan gaya format yang berbeda? (Harap dicatat bahwa saya mencari argumen tentang manfaat, bukan "Saya belum pernah mendengarnya" atau "Saya tidak peduli.")
• Berbicara secara empiris, berapa persen repositori Git merangkul gaya ini? (Jika seseorang ingin melakukan analisis pada repositori GitHub ... petunjuk, petunjuk.)

Maksud saya di sini bukan untuk merekomendasikan gaya 50/72 atau menembak jatuh gaya lain. (Untuk terbuka tentang hal itu, saya lebih suka itu, tetapi saya terbuka untuk ide-ide lain.) Saya hanya ingin mendapatkan alasan mengapa orang menyukai atau menentang berbagai gaya pesan Git commit. (Jangan ragu untuk memunculkan poin yang belum disebutkan.)

Mengenai baris "ringkasan" (50 dalam rumus Anda), dokumentasi kernel Linux mengatakan ini :

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

Yang mengatakan, sepertinya pemelihara kernel memang mencoba untuk menjaga hal-hal di sekitar 50. Berikut adalah histogram dari panjang garis ringkasan di log git untuk kernel:

( lihat ukuran penuh )

Ada beberapa komit yang memiliki garis ringkasan yang lebih panjang (beberapa lebih lama) daripada yang bisa dipegang plot ini tanpa membuat bagian yang menarik terlihat seperti satu baris tunggal. (Mungkin ada beberapa teknik statistik mewah untuk menggabungkan data itu di sini tapi oh well ... :-)

Jika Anda ingin melihat panjang mentah:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

atau histogram berbasis teks:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

Mengenai "pemimpin pemikiran": Linus dengan tegas mendukung pembungkus baris untuk pesan komitmen penuh:

[…] Kami menggunakan kolom 72 karakter untuk pembungkus kata, kecuali untuk materi yang dikutip yang memiliki format baris tertentu.

Pengecualian merujuk terutama pada teks "non-prosa", yaitu, teks yang tidak diketik oleh manusia untuk komit - misalnya, pesan kesalahan kompiler.

Pemisahan presentasi dan data mendorong pesan komit saya di sini.

Pesan komit Anda tidak boleh terbebani dengan jumlah karakter apa pun dan sebaliknya jeda baris harus digunakan untuk memisahkan pikiran, paragraf, dll. Sebagai bagian dari data, bukan presentasi. Dalam hal ini, "data" adalah pesan yang Anda coba sampaikan dan "presentasi" adalah bagaimana pengguna melihatnya.

Saya menggunakan garis ringkasan tunggal di bagian atas dan saya mencoba untuk membuatnya singkat tetapi saya tidak membatasi diri saya ke nomor yang sewenang-wenang. Akan jauh lebih baik jika Git benar-benar menyediakan cara untuk menyimpan pesan ringkasan sebagai entitas terpisah dari pesan tersebut tetapi karena saya tidak perlu meretasnya dan saya menggunakan baris pertama sebagai pembatas (untungnya, banyak alat mendukung ini berarti memecah data).

Untuk pesan itu sendiri baris baru menunjukkan sesuatu yang berarti dalam data. Sebuah baris baru menunjukkan awal / istirahat dalam daftar dan baris ganda ganda menunjukkan pemikiran / ide baru.

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

Begini tampilannya pada pemirsa yang membungkus teks dengan lembut.

Ini adalah garis ringkasan, cobalah untuk tetap pendek dan akhiri dengan satu baris.

Ini adalah pemikiran, mungkin penjelasan tentang apa yang telah saya lakukan dalam format yang dapat dibaca manusia. Mungkin rumit dan panjang yang terdiri dari beberapa kalimat yang menggambarkan pekerjaan saya dalam format esai. Bukan hak saya untuk memutuskan sekarang (saat penulis) bagaimana pengguna akan mengkonsumsi data ini.

Ada dua garis yang memisahkan dua pemikiran ini. Pengguna mungkin membaca ini di telepon atau monitor layar lebar. Apakah Anda pernah mencoba membaca 72 karakter yang dibungkus teks pada perangkat yang hanya menampilkan 60 karakter? Ini benar-benar pengalaman yang menyakitkan. Juga, kalimat pembuka paragraf ini (dengan asumsi format gaya esai) harus menjadi intro ke paragraf jadi jika alat memilihnya mungkin ingin tidak membungkus otomatis dan membiarkan Anda melihat awal setiap paragraf. Sekali lagi, tergantung pada alat presentasi, bukan saya (penulis acak di beberapa titik dalam sejarah) untuk mencoba memaksa format khusus saya ke tenggorokan orang lain.

Sama seperti contoh, berikut adalah daftar poin:
* Titik 1.
* Titik 2.
* Titik 3.

Kecurigaan saya adalah bahwa penulis Git melakukan rekomendasi pesan yang Anda tautkan tidak pernah menulis perangkat lunak yang akan dikonsumsi oleh beragam pengguna akhir pada perangkat yang berbeda sebelumnya (yaitu, situs web) karena pada titik ini dalam evolusi perangkat lunak / komputasi diketahui bahwa menyimpan data Anda dengan informasi presentasi yang dikodekan keras adalah ide yang buruk sejauh pengalaman pengguna.

Saya setuju bahwa menarik untuk mengusulkan gaya kerja tertentu. Namun, kecuali saya memiliki kesempatan untuk mengatur gaya, saya biasanya mengikuti apa yang telah dilakukan untuk konsistensi.

Melihat Linux Kernel Commits, proyek yang memulai git jika Anda suka, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , mereka tidak mengikuti aturan 50/72. Baris pertama adalah 54 karakter.

Saya akan mengatakan konsistensi penting. Siapkan cara yang tepat untuk mengidentifikasi pengguna yang telah membuat komitmen (user.name, user.email - terutama di jaringan internal. Pengguna @ OFFICE-1-PC-10293982811111 bukan alamat kontak yang berguna). Bergantung pada proyek, buat detail yang sesuai tersedia di komit. Sulit mengatakan apa yang seharusnya; itu mungkin tugas yang diselesaikan dalam proses pengembangan, kemudian perincian tentang apa yang berubah.

Saya tidak percaya pengguna harus menggunakan git satu cara karena antarmuka tertentu untuk git memperlakukan komit dengan cara tertentu.

Saya juga harus mencatat ada cara lain untuk menemukan komitmen. Sebagai permulaan, git diffakan memberi tahu Anda apa yang berubah. Anda juga dapat melakukan hal-hal seperti git log --pretty=format:'%T %cN %ce'memformat opsi git log.

Apakah panjang judul maksimum yang disarankan adalah 50?

Saya telah mempercayai ini selama bertahun-tahun, tetapi ketika saya baru saja memperhatikan dokumentasi "git commit" sebenarnya menyatakan

$ git help commit | grep -C 1 50
      Though not required, it’s a good idea to begin the commit message with
      a single short (less than 50 character) line summarizing the change,
      followed by a blank line and then a more thorough description. The text

$  git version
git version 2.11.0

Orang bisa berpendapat bahwa "kurang dari 50" hanya bisa berarti "tidak lebih dari 49".