ข้อความคอมมิท Git: การจัดรูปแบบ 50/72

ทิมสมเด็จพระสันตะปาปาระบุว่าสำหรับเฉพาะ Git กระทำสไตล์ข้อความโพสต์ในบล็อกของเขา: http://www.tpope.net/node/106

นี่คือบทสรุปโดยย่อของสิ่งที่เขาแนะนำ:

• บรรทัดแรกคือ 50 ตัวอักษรหรือน้อยกว่า
• จากนั้นเป็นบรรทัดว่าง
• ข้อความที่เหลือควรห่อหุ้มด้วยตัวอักษร 72 ตัว

โพสต์บล็อกของเขาให้เหตุผลสำหรับคำแนะนำเหล่านี้ (ซึ่งฉันจะเรียกว่า "การจัดรูปแบบ 50/72" เพื่อความกระชับ):

• ในทางปฏิบัติเครื่องมือบางอย่างถือว่าบรรทัดแรกเป็นหัวเรื่องและย่อหน้าที่สองเป็นเนื้อหา (คล้ายกับอีเมล)
• git log ไม่จัดการกับการพันดังนั้นจึงเป็นการยากที่จะอ่านหากบรรทัดยาวเกินไป
• git format-patch --stdout แปลงคอมมิทให้เป็นอีเมล - ดังนั้นการเล่นที่ดีจะช่วยได้หากคอมแพ็คของคุณถูกห่อไว้เรียบร้อยแล้ว

ประเด็นที่ฉันต้องการเพิ่มที่ฉันคิดว่าทิมจะเห็นด้วยกับ:

• การสรุปการกระทำของคุณเป็นการฝึกฝนที่ดีในระบบควบคุมเวอร์ชันใด ๆ ช่วยให้ผู้อื่น (หรือหลังจากนั้น) พบการกระทำที่เกี่ยวข้องได้เร็วขึ้น

ดังนั้นฉันมีมุมสองสามคำถามของฉัน:

• อะไรคือ "ผู้นำทางความคิด" หรือ "ผู้ใช้ที่มีประสบการณ์" ของ Git ที่ยอมรับสไตล์การจัดรูปแบบ 50/72 ฉันถามสิ่งนี้เพราะบางครั้งผู้ใช้ใหม่ไม่รู้หรือไม่สนใจแนวทางปฏิบัติของชุมชน
• สำหรับผู้ที่ไม่ได้ใช้การจัดรูปแบบนี้มีเหตุผลหลักในการใช้รูปแบบการจัดรูปแบบที่แตกต่างกันหรือไม่? (โปรดทราบว่าฉันกำลังมองหาข้อโต้แย้งเกี่ยวกับข้อดีไม่ใช่ "ฉันไม่เคยได้ยิน" หรือ "ฉันไม่สนใจ")
• สังเกตุอย่างชัดแจ้งว่าที่เก็บของ Git โอบกอดสไตล์นี้กี่เปอร์เซ็นต์ (ในกรณีที่มีคนต้องการวิเคราะห์ที่เก็บข้อมูลของ GitHub …คำใบ้คำใบ้)

จุดของฉันที่นี่คือไม่แนะนำสไตล์ 50/72 หรือยิงสไตล์อื่น ๆ (เพื่อเปิดเกี่ยวกับมันฉันชอบมัน แต่ฉันเปิดรับความคิดอื่น ๆ ) ฉันแค่ต้องการทราบเหตุผลว่าทำไมผู้คนถึงชอบหรือคัดค้านรูปแบบข้อความต่าง ๆ ของ Git (อย่าลังเลที่จะนำเสนอประเด็นที่ไม่ได้กล่าวถึงเช่นกัน)

เกี่ยวกับบรรทัด“ สรุป” (50 ในสูตรของคุณ) เอกสารของเคอร์เนลของ Linux มีดังนี้:

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.

ที่กล่าวว่าดูเหมือนว่าผู้ดูแลเคอร์เนลพยายามเก็บสิ่งต่าง ๆ ประมาณ 50 นี่คือฮิสโตแกรมของความยาวของบรรทัดสรุปในบันทึก git สำหรับเคอร์เนล:

( ดูขนาดเต็ม )

มีการประจบประแจงของการผูกมัดที่มีบรรทัดสรุปที่ยาวกว่า (บางส่วนนานกว่า) พล็อตนี้สามารถเก็บไว้ได้โดยไม่ทำให้ส่วนที่น่าสนใจดูเหมือนหนึ่งบรรทัดเดียว (อาจมีเทคนิคทางสถิติแฟนซีสำหรับการรวมข้อมูลที่นี่ แต่แหม… :-)

หากคุณต้องการดูความยาวดิบ:

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

หรือฮิสโตแกรมที่ยึดข้อความ:

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

เกี่ยวกับ“ ผู้นำทางความคิด”: ไลนัสสนับสนุนการตัดบรรทัดเพื่อส่งข้อความที่สมบูรณ์:

[…] เราใช้คอลัมน์ 72 ตัวอักษรเพื่อตัดคำยกเว้นวัสดุที่ยกมาซึ่งมีรูปแบบบรรทัดเฉพาะ

ข้อยกเว้นส่วนใหญ่อ้างถึงข้อความ "ไม่ใช่ร้อยแก้ว" นั่นคือข้อความที่ไม่ได้พิมพ์โดยมนุษย์สำหรับการส่งมอบ - ตัวอย่างเช่นข้อความแสดงข้อผิดพลาดของคอมไพเลอร์

การแยกงานนำเสนอและข้อมูลทำให้การส่งข้อความของฉันตรงนี้

ข้อความยืนยันของคุณไม่ควรถูกห่อหุ้มด้วยจำนวนอักขระใด ๆและควรใช้เส้นแบ่งบรรทัดเพื่อแยกความคิดย่อหน้า ฯลฯ เป็นส่วนหนึ่งของข้อมูลไม่ใช่การนำเสนอ ในกรณีนี้ "ข้อมูล" คือข้อความที่คุณพยายามจะดำเนินการและ "การนำเสนอ" เป็นวิธีที่ผู้ใช้มองเห็น

ฉันใช้บรรทัดสรุปเดียวที่ด้านบนและฉันพยายามทำให้สั้น แต่ฉันไม่ จำกัด ตัวเองเป็นหมายเลขที่กำหนดเอง มันจะดีกว่านี้ถ้า Git ให้วิธีการจัดเก็บข้อความสรุปเป็นเอนทิตีแยกต่างหากจากข้อความ แต่เนื่องจากฉันไม่ต้องแฮ็คหนึ่งและฉันใช้ตัวแบ่งบรรทัดแรกเป็นตัวคั่น (โชคดีเครื่องมือสนับสนุนจำนวนมาก นี่หมายถึงการแยกข้อมูล)

สำหรับข้อความที่ขึ้นบรรทัดใหม่บ่งบอกถึงสิ่งที่มีความหมายในข้อมูล ขึ้นบรรทัดใหม่เดียวระบุการเริ่มต้น / การหยุดพักในรายการและการขึ้นบรรทัดใหม่สองครั้งเป็นการระบุความคิด / ความคิดใหม่

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.

นี่คือสิ่งที่ดูเหมือนในโปรแกรมดูที่นุ่มห่อหุ้มข้อความ

นี่คือบรรทัดสรุปพยายามทำให้สั้นและลงท้ายด้วยตัวแบ่งบรรทัด

นี่เป็นความคิดบางทีคำอธิบายของสิ่งที่ฉันทำในรูปแบบที่มนุษย์อ่านได้ มันอาจจะซับซ้อนและมีความยาวประกอบด้วยหลายประโยคที่อธิบายงานของฉันในรูปแบบเรียงความ ฉันไม่สามารถตัดสินใจได้ในขณะนี้ (ณ เวลาที่เขียน) ว่าผู้ใช้จะใช้ข้อมูลนี้อย่างไร

ตัวแบ่งสองบรรทัดแยกความคิดทั้งสองนี้ ผู้ใช้อาจกำลังอ่านสิ่งนี้ทางโทรศัพท์หรือจอภาพขนาดใหญ่ คุณเคยลองอ่านข้อความที่ห่อหุ้มตัวอักษร 72 ตัวบนอุปกรณ์ที่แสดงเพียง 60 ตัวอักษรหรือไม่? มันเป็นประสบการณ์ที่เจ็บปวดอย่างแท้จริง นอกจากนี้ประโยคเปิดของย่อหน้านี้ (สมมติว่ารูปแบบการเขียนเรียงความ) ควรเป็นคำนำในย่อหน้าดังนั้นหากเครื่องมือเลือกมันอาจไม่ต้องการตัดคำอัตโนมัติและให้คุณเห็นจุดเริ่มต้นของแต่ละย่อหน้า อีกครั้งมันขึ้นอยู่กับเครื่องมือการนำเสนอไม่ใช่ฉัน (ผู้เขียนแบบสุ่ม ณ จุดใดจุดหนึ่งในประวัติศาสตร์) เพื่อพยายามบังคับให้ฉันจัดรูปแบบเฉพาะลงในลำคอของคนอื่น

นี่เป็นรายการของจุด:
* จุดที่ 1
* จุดที่ 2
* จุดที่ 3

ความสงสัยของฉันคือผู้เขียน Git ยอมรับข้อเสนอแนะข้อความที่คุณเชื่อมโยงไม่เคยเขียนซอฟต์แวร์ที่จะใช้งานโดยผู้ใช้ปลายทางที่หลากหลายบนอุปกรณ์ต่าง ๆ มาก่อน (เช่นเว็บไซต์) ตั้งแต่จุดนี้ในวิวัฒนาการของซอฟต์แวร์ / คอมพิวเตอร์ เป็นที่ทราบกันดีว่าการจัดเก็บข้อมูลของคุณด้วยข้อมูลงานนำเสนอที่กำหนดโค้ดยากถือเป็นแนวคิดที่ไม่ดีเท่าที่ประสบการณ์ของผู้ใช้จะดำเนินต่อไป

ฉันเห็นด้วยที่น่าสนใจที่จะเสนอรูปแบบการทำงานที่เฉพาะเจาะจง อย่างไรก็ตามถ้าฉันไม่มีโอกาสได้กำหนดสไตล์ฉันมักจะทำตามสิ่งที่ทำเพื่อความมั่นคง

ลองดูที่ Linux Kernel Commits โปรเจ็กต์ที่เริ่มต้นคอมไพล์หากคุณต้องการhttp://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3พวกเขาไม่ปฏิบัติตามกฎ 50/72 บรรทัดแรกคือ 54 ตัวอักษร

ฉันจะบอกว่าเรื่องความมั่นคง ตั้งค่าวิธีที่เหมาะสมในการระบุผู้ใช้ที่ได้ทำสัญญาไว้ (user.name, user.email - โดยเฉพาะในเครือข่ายภายในผู้ใช้ @ OFFICE-1-PC-10293982811111 ไม่ใช่ที่อยู่ติดต่อที่มีประโยชน์) ขึ้นอยู่กับโครงการทำให้รายละเอียดที่เหมาะสมมีอยู่ในการกระทำ มันยากที่จะพูดในสิ่งที่ควรจะเป็น; อาจเป็นงานที่เสร็จสิ้นในกระบวนการพัฒนาแล้วรายละเอียดของสิ่งที่เปลี่ยนแปลง

ฉันไม่เชื่อว่าผู้ใช้ควรใช้คอมไพล์ทางเดียวเนื่องจากอินเทอร์เฟซบางอย่างในการคอมไพล์จัดการกับคอมมิทในบางวิธี

ฉันควรทราบว่ามีวิธีอื่นในการค้นหาความมุ่งมั่น สำหรับการเริ่มต้นgit diffจะบอกคุณว่ามีอะไรเปลี่ยนแปลง นอกจากนี้คุณยังสามารถทำสิ่งต่างๆเช่นการจัดรูปแบบตัวเลือกของgit log --pretty=format:'%T %cN %ce'git log

ความยาวสูงสุดของชื่อที่แนะนำคือ 50 จริงๆหรือไม่?

ฉันเชื่อเรื่องนี้มาหลายปีแล้ว แต่เมื่อฉันเพิ่งสังเกตเห็นเอกสารของ "git commit" ที่จริงแล้ว

$ 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

หนึ่งอาจโต้แย้งว่า "น้อยกว่า 50" สามารถหมายถึง "ไม่เกิน 49" เท่านั้น