คู่มือสไตล์การใช้งาน Git

คู่มือสไตล์การเขียน Git นี้ได้รับแรงบันดาลใจมาจาก How to Get Your Change Into the Linux Kernel, git man pages และ ข้อที่ควรปฏิบัติที่เป็นนิยมในชุมชน

คู่มือที่มีการผ่านการแปลภาษามีภาษาดังต่อไปนี้ :

• Chinese (Simplified)
• Chinese (Traditional)
• French
• Japanese
• Korean
• Portuguese
• Thai
• Ukrainian

ถ้าคุณรู้สึกว่าอยากจะมีส่วนร่วมกับเรา โปรดทำแบบนี้! Fork โปรเจ็คนี้ และเปิด pull request

ตารางสารบัญ

1. Branches
2. Commits
   1. Messages
3. Merging
4. Misc.

Branches

• ควรเลือกชื่อที่ สั้นกระชับ และ บอกรายละเอียดเฉพาะตัวได้ :

   # ควรใช้
   $ git checkout -b oauth-migration
  
   # ไม่ควรใช้ - เพราะกำกวมเกินไป
   $ git checkout -b login_fix

• ระบุถึง tickets ที่ตรงกันกับใน service ภายนอก (ตัวอย่างเช่น GitHub issue) นอกจากนี้ยังมีรูปแบบที่เหมาะ สำหรับการใช้งานใน branch ยกตัวอย่างเช่น:

   # GitHub issue #15
   $ git checkout -b issue-15

• ควรใช้ ขีดกลาง ( - ) เพื่อแยกคำออกจากกัน

• ในขณะที่มีคนหลายๆคนทำงานอยู่บนฟีเจอร์ที่ เหมือนกัน มีแนวทางที่ง่ายและสะดวกสำหรับการใช้งาน branches ในส่วน ฟีเจอร์ สำหรับบุคคล และ สำหรับทีม ซึ่งควรใช้การตั้งชื่อแบบนี้เพื่อการแบ่งแยกให้ง่ายขึ้น:

   $ git checkout -b feature-a/master # team-wide branch
   $ git checkout -b feature-a/maria  # Maria's personal branch
   $ git checkout -b feature-a/nick   # Nick's personal branch

  Merge ส่วน branche แต่ละบุคคล ไปยังส่วน branch สำหรับทีม (ดูหัวข้อ "Merging") และสุดท้าย branch สำหรับทีม จะถูก merged เข้าไปรวมกับ "master"

• แนะนำให้ลบ branch ออกจาก upstream repository หลังจากที่มัน merged กันเสร็จเรียบร้อย (ยกเว้นแต่จะมีเหตุผล)

  ข้อแนะนำ: ใช้คำสั่งต่อไปเมื่ออยู่บน "master" เพื่อแสดงรายการ merge แล้ว branches:

   $ git branch --merged | grep -v "\*"

Commits

• ทุกๆ commit ควรจะเป็น การเปลี่ยนแปลงโลจิกเฉพาะส่วนนั้นๆ. อย่าเหมารวมเอา หลายๆการเปลี่ยนเปลี่ยนโลจิก ไว้ใน commit เดียว ตัวอย่างเช่น ถ้าสมมุติ มี patch ในแก้ไข bug และ optimizes เพื่อประสิทธิภาพของ feature ควรจะแบ่งมันออกเป็น 2 commit

• อย่าแบ่งการเปลียนแปง แบบเจาะจง ออกเป็นหลายๆ commits. ตัวอย่างเช่น ในการดำเนินการของ feature และ การทดสอบเป้นส่วนๆ ควรจะอยู่ใน commit เดียวกัน

• ควรจะมี commit แต่ เนิ่นๆ และ บ่อยๆ ในจุดเล็กๆน้อย เพื่อให้ง่ายต่อการเข้าใจ และ สามารถย้อนกลับได้เมื่อมีอะไรผิดพลาด

• ในการ commit ควรจะมีการเรียงลำดับ อย่างมีเหตุผล. ตัวอย่างเช่น ถ้า commit X มีการเปลียนแปลงในส่วน commit Y ดังนั้น commit Y ควรจะมาก่อน commit X

Messages

• ควรใช้พวก editor ต่างๆ ในการเขียนข้อความสำหรับ commit ไม่แนะนำให้ใช้ผ่าน terminal :

   # ควรใช้
   $ git commit
  
   # ไม่ควรใช้
   $ git commit -m "Quick fix"

  เมื่อมีการ commit จาก terminal จะส่งผลให้เกิดแนวคิดที่ว่าให้ทุกสิ่งอย่างอยู่ใน บรรทัดเดียว ซึ่งอาจจะทำให้เกิดผลกระทบในความไม่ชัดเจนของความหมายของข้อความที่ส่งไป

• บรรทัดหัวข้อสรุป (อาทิเช่น บรรทัดแรกของข้อความ) ควรจะมี การบรรยาย แต่อย่าง กระชับ ซึ่งจะเป็นการดี ถ้าไม่มันยาวเกินไปกว่า 50 ตัวอักษร. It should be capitalized and written in imperative present tense. It should not end with a period since it is effectively the commit title:

   # ควรใช้ - ใช้ตามความจำเป็นในขณะนั้นซึ่งไม่ควรเกินกว่า 50 ตัวอักษร
   Mark huge records as obsolete when clearing hinting faults
  
   # ไม่ควรใช้
   fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.

• หลังจากนั้นควรมาพร้อมบรรทัดว่างตามด้วยอธิบายเพิ่มเติมอย่างละเอียด มันควรจะประกอบไปด้วย 72 ตัวอักษร และ อธิบายเหตุผลด้วยว่า ทำไม การเปลี่ยนนี้ถึงจำเป็น และ ทำอย่างไร ตามจุดประสงค์ และ คำนึงถึง ผลกระทบ ที่อาจจะมี

  นอกจากนี้ยังควรให้คำแนะนำต่างๆให้ไปแหล่งข้อมูลอื่นๆที่เกี่ยวข้อง ( อาทิเช่น การอ้างอิงไปยังปัญหาที่เกี่ยวเนื่องกันในจุดบกพร่อง ):

   Short (50 chars or fewer) summary of changes
  
   More detailed explanatory text, if necessary. Wrap it to
   72 characters. In some contexts, the first
   line is treated as the subject of an email and the rest of
   the text as the body.  The blank line separating the
   summary from the body is critical (unless you omit the body
   entirely); tools like rebase can get confused if you run
   the two together.
  
   Further paragraphs come after blank lines.
  
   - Bullet points are okay, too
  
   - Use a hyphen or an asterisk for the bullet,
   	followed by a single space, with blank lines in
   	between
  
   Source http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

  ในท้ายที่สุดแล้ว เมื่อ เขียนข้อความสำหรับ commit ต้องคิดเกี่ยวกับสิ่งที่ต้องการถ้ารู้ว่าคุณต้องทำงานใน commit ในหนึ่งปีจากนี้ไป

• ถ้า commit A ขึ้นอยู่กับ commit B ควรจะต้องถูกแจ้งไว้กับข้อความของ commit A Use the commit's hash when referring to commits.

  Similarly, if commit A solves a bug introduced by commit B, it should be stated in the message of commit A.

• If a commit is going to be squashed to another commit use the --squash and --fixup flags respectively, in order to make the intention clear:

   $ git commit --squash f387cab2

  (ข้อแนะนำ: ควรใช้ --autosquash flag when rebasing. The marked commits will be squashed automatically.)

Merging

• Do not rewrite published history. The repository's history is valuable in its own right and it is very important to be able to tell what actually happened. Altering published history is a common source of problems for anyone working on the project.

• However, there are cases where rewriting history is legitimate. These are when:

  • You are the only one working on the branch and it is not being reviewed.

  • You want to tidy up your branch (eg. squash commits) and/or rebase it onto the "master" in order to merge it later.

  That said, never rewrite the history of the "master" branch or any other special branches (ie. used by production or CI servers).

• ควรเก็บประวัติอย่าง clean and simple. Just before you merge branch ของคุณ:

    1. Make sure it conforms to the style guide and perform any needed actions
    	 if it doesn't (squash/reorder commits, reword messages etc.)
  
    2. Rebase it onto the branch it's going to be merged to:
  
    	 ```shell
    	 [my-branch] $ git fetch
    	 [my-branch] $ git rebase origin/master
    	 # then merge
    	 ```
  
    	 This results in a branch that can be applied directly to the end of the
    	 "master" branch and results in a very simple history.
  
    	 *(Note: This strategy is better suited for projects with short-running
    	 branches. Otherwise it might be better to occassionally merge the
    	 "master" branch instead of rebasing onto it.)*
  

• ถ้าหาก branch ของคุณมีมากกว่าหนึ่ง commit มันไม่สมควร merge ไปข้างหน้าอย่างเร่งรีบ :

   # ควรใช้ - เพื่อให้แน่ใจว่าการ merge จะถูกสร้างขึ้น
   $ git merge --no-ff my-branch
  
   # ไม่ควรใช้
   $ git merge my-branch

Misc.

• There are various workflows and each one has its strengths and weaknesses. Whether a workflow fits your case, depends on the team, the project and your development procedures.

  That said, it is important to actually choose a workflow and stick with it.

• Be consistent. This is related to the workflow but also expands to things like commit messages, branch names and tags. Having a consistent style throughout the repository makes it easy to understand what is going on by looking at the log, a commit message etc.

• Test before you push. Do not push half-done work.

• Use annotated tags for marking releases or other important points in the history. Prefer lightweight tags for personal use, such as to bookmark commits for future reference.

• Keep your repositories at a good shape by performing maintenance tasks occasionally, in your local และ remote repositories:

  • git-gc(1)
  • git-prune(1)
  • git-fsck(1)

License

This work is licensed under a Creative Commons Attribution 4.0 International license.

Credits

Agis Anastasopoulos / @agisanast / http://agis.io

Translator

Kitti Pariyaakkarakun