راهنمای عملی برای نوشتن Commit Message در Git

git

یکی از مشکلاتی که برنامه نویس ها و بخصوص تیم های برنامه نویسی با آن مواجه هستند، Commit Messageهای ناخوانا و نا کارامد است. در این مقاله سعی شده تا نحوه نوشتن یک Commit Message موثر، شرح داده شود.

در ابتدا تیم ها باید در مورد قرارداد استفاده از Commit Messageها توافق کنند. این مورد درباره پروژه های شخصی نیز صدق میکند.

مقدمه ای برای کنترل نسخه با Git

نرم افزار کنترل نسخه بخشی اساسی از برنامه های امروزی توسعه نرم افزار است.

تا کنون ، Git پرکاربردترین سیستم کنترل نسخه در جهان است. این یک پروژه منبع باز توزیع شده و فعال است که در ابتدا در سال 2005 توسط لینوس توروالدز ، خالق معروف هسته سیستم عامل لینوکس توسعه یافته است.

Commit Message چیست؟

از دستور commit برای ذخیره تغییرات در مخزن محلی پس از مرحله بندی در Git استفاده می شود. با این حال ، قبل از ذخیره تغییرات در Git ، باید به Git بگویید که می خواهید کدام تغییرات را ذخیره کنید زیرا ممکن است تعداد زیادی ویرایش انجام داده باشید. یک روش عالی برای انجام این کار افزودن Commit Message برای شناسایی تغییرات شماست.

گزینه های Commit

  • m-

این گزینه commit message را تنظیم میکند

git add static/admin/config.yml
git commit -m "Setup multiple roles for netlify-cms git gateway"
  • all- یا a-

این گزینه به طور خودکار تمام پرونده های ردیابی شده ، اصلاح شده یا حذف شده (از جمله جدید) را commit میکند.

git commit -a -m "Add a new role for netlify-cms git gateway"
  • amend-

این گزینه آخرین commit را با هرگونه تغییر در مرحله انجام شده یا commit message جدید بازنویسی می کند و باید فقط در commitهای انجام شود که هنوز به مخزن remote منتقل نشده اند.

git add .
git commit --amend -m "Update roles for netlify-cms git gateway"

چرا باید Commit Message خوبی بنویسیم؟

ممکن است بگویید: “این فقط یک پروژه شخصی است.” بله ، شما اکنون به تنهایی کار می کنید ، اما چه اتفاقی می افتد اگز با یک تیم کار کنید یا به یک پروژه منبع باز کمک کنید؟

Commit Message خوب در Git بهترین راه برای برقراری ارتباط در مورد تغییر با سایر توسعه دهندگان که در آن پروژه کار می کنند و در واقع ، در آینده به خود شما است.

آیا تا به حال سعی کرده اید git logدر یکی از پروژه های قدیمی خود اجرا کنید تا Commit Messageهای “عجیب و غریب” را که از ابتدای کار استفاده کرده اید ، ببینید؟ درک اینکه چرا برخی تغییرات را در گذشته ایجاد کرده اید دشوار است و آرزو می کنید این مقاله را زودتر خوانده بودید :).

Commit Messageها می توانند به درستی دلیل ایجاد تغییر را بیان کنند ، و درکی که باعث می شود توسعه و همکاری موثرتر باشد را به وجود آورند.

نحوه نوشتن Commit Message در Git

پیش تر من فقط از git commit -m "Fix X to allow Y to use Z" در پروژه های شخصی خود استفاده می کردم، فقط با یک موضوف و بدون توضیح. این برای تغییرات کوچک و واضح مثل git commit -m "Fix typo in README.md مناسب است، اما در مورد تغییرات گسترده تر، باید جزئیات بیشتری اضافه کنید.

روش ویرایشگر

git commit را بدون پیغام یا گزینه ای اجرا کنید تا ویرایشگر متن پیش فرض شما برای نوشتن یک Commit Message باز شود. برای تنظیم ویرایشگر پیش فرض، دستور زیر را اجرا کنید:

git config --global core.editor nano

به این ترتیب Git تنظیم میشود تا از nano به عنوان ویرایشگر پیش فرض استفاده کند. “nano” را با “emacs”, “wim”, یا هر ویرایشگر متن دلخواه جایگزین کنید.

در ویرایشگر باز شده، اولین خط، موضوع (توضیح کوتاه) است. بعد از آن یک خط خالی بگذارید و هر چیزی بعد از آن، توضیحات کامل (بدنه) است.

<Summarize change(s) in around 50 characters or less>

<More detailed explanatory description of the change wrapped into about 72
characters>

روش خط فرمان

git commit -m "Subject" -m "Description..."

اولین -mگزینه موضوع است (توضیح کوتاه) ، و گزینه بعدی توضیحات گسترده (بدنه) است.

چگونه Commit Messageهای خوب بنویسیم

چندین قرارداد وجود دارد که توسط تیم ها و توسعه دهندگان مختلف برای نوشتن Commit Messageهای خوب استفاده می شود. من فقط برخی از قوانین و نکات کلی برای نوشتن Commit Messageها را شرح می دهم – شما باید تصمیم بگیرید که چه قراردادی را دنبال کنید. و اگر در یک شرکت کار می کنید یا در منبع باز همکاری می کنید ، باید با قرارداد آنها سازگار شوید :).

برای سازگاری ، می توانید از یک قرارداد برای کار و دیگری برای پروژه های شخصی استفاده کنید زیرا ممکن است زمانی شغل خود را تغییر دهید ، و قرارداد نیز ممکن است تغییر کند.

حتماً این موضوع را برای برخی از قراردادهای شگفت انگیزCommit Message بررسی کنید یا موارد دیگری را اضافه کنید تا به کسی در تصمیم گیری کمک کنید

در اینجا یک الگوی عالی از یک پیام متعهد خوب است که در اصل توسط تیم پاپ نوشته شده است:

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  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.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

If you use an issue tracker, add a reference(s) to them at the bottom,
like so:

Resolves: #123

عالی به نظر میرسد، اینطور نیست؟ حالا چطور Commit Message خودتان را عالی کنید:

  1. نوع commit را مشخص کنید:
  • feat: ویژگی جدیدی که به برنامه اضافه می کنید
  • fix: رفع اشکال
  • style: ویژگی و به روزرسانی های مربوط به طراحی ظاهر
  • refactor: refactoring بخش خاصی از کد
  • test: هر آنچه مربوط به تست است
  • docs: هر آنچه مربوط به مستندات است
  • chore: نگهداری منظم کد. [برای نمایش انواع commit می توانید از شکلک نیز استفاده کنید]
  1. سوژه را با یک خط خالی از بدن جدا کنید
  2. پیام commit شما نباید دارای خطاهای فضای سفید باشد
  3. علائم نگارشی غیرضروری را حذف کنید
  4. موضوع را با نقطه به پایان نبرید
  5. حروف اول اولین کلمات خط موضوع و هر پاراگراف را بزرگ بنویسید
  6. از حالت امری در خط موضوع استفاده کنید
  7. از بدنه برای توضیح اینکه چه تغییری ایجاد کرده اید و چرا آنها را ایجاد کرده اید استفاده کنید.
  8. تصور نکنید که شخصی که بازنگری می کند می فهمد مشکل اصلی چیست ، اطمینان حاصل کنید که آن را شرح می دهید.
  9. فکر نکنید کد شما خودش توضیح می دهد
  10. قرارداد commit را که توسط تیم شما تعریف شده دنبال کنید

نتیجه

مهمترین قسمت Commit Message این است که پیام باید واضح و معنادار باشد. در طولانی مدت ، نوشتن پیام های commit خوب نشان می دهد که چقدرهمکار خوبی هستید. مزایای نوشتن پیام های commit خوب فقط به تیم شما محدود نمی شود ، بلکه در واقع به خودتان و همکاران آینده گسترش می یابد.

آیا می خواهید در مورد Git اطلاعات بیشتری کسب کنید و به یک “کنترل کننده نسخه” حرفه ای تبدیل شوید؟ این منابع عالی را بررسی کنید

منبع: How to Write Good Commit Messages: A Practical Git Guide

برچسب‌ها:

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

این سایت از اکیسمت برای کاهش هرزنامه استفاده می کند. بیاموزید که چگونه اطلاعات دیدگاه های شما پردازش می‌شوند.