Блог им. dmitrys99
101

Об оформлении коммитов Git



Хочу кратко остановиться на том, что представляет собой хороший комментарий коммита.
Коммиты и работа с ними — вот что делает Git великолепным.

Примерная структура хорошего комментария к коммиту:

Краткая сводка (summary) (до 50 знаков), с заглавной буквы

Если нужно, более детальный пояснительный текст. Следует выравнивать
текст комментария примерно до 72 символов. В некоторых ситуациях, первая
строка используется как тема электронного письма, остальные - как тело.
Пустая строка, отделяющая сводку от тела, важна (если тело письма
присутствует, разумеется). Утилиты вроде rebase могут запутаться, если
части комментария не разделить.

Пишите комментарий к коммиту в повелительном наклонении: "Исправление 
ошибки", но не "Исправлена ошибка" или "Исправляет ошибки". Это 
согласуется с комментариями, генерируемыми утилитами вроде git merge
или git revert.

Абзацы отделяются пустыми строками.

- Можно использовать маркеры

- Обычно в качестве маркеров используется дефис или звездочка с пробелом
  и пустой строкой в промежутках, но могут быть и другие варианты.
  
- Выступы также вполне применимы


Позвольте пояснить, почему стоит переносить строки на 72 символах.

  • git log специально не переносит комментарии коммита. Это значит, что при использовании пейджера по-умолчанию (less -S) абзацы будут утекать далеко за пределы экрана, затрудняя чтение. На 80-символьных терминалах, если мы вычтем 4 символа на отбивку и справа 4 символа для симметрии, как раз и получится 72 позиции.
  • git format-patch —stdout преобразует серию коммитов в набор электронных сообщений, используя комментарий как тело письма. Сетевой этикет предписывает нам переносить строки в письмах таким образом, чтобы оставалось место для нескольких индикаторов уровней вложения без превышения 80 символов. Возможно сейчас в проекте не используется электронная почта вместе с Git, но кто знает, как ситуация повернется в будущем?

Однако, наличие сводки комментария гораздо более важно, нежели форматирование тела комментария. Как показано в примере, следует пытаться вписаться в 50 символов (что, впрочем, не жесткий максимум) и всегда, обязательно, ставить пустую строку после сводки. Первая строка должна содержать краткое резюме изменений, выполняемых коммитом; если же есть технические детали, которые не укладываются в столь небольшой объем, помещайте их в тело комментария. Сводка повсеместно используется Git и часто используется именно усеченная форма комментария. Вот несколько примеров:

  • git log —pretty=oneline показывает краткую историю, содержащую идентификатор коммита и сводку;
  • git rebase —interactive предоставляет сводку каждого коммита в вызванном редакторе;
  • Если установлена опция merge.summary, то при слиянии заголовки всех коммитов собираются в комментарий к общему коммиту;
  • git shortlog использует сводку при создании changelog-подобного вывода;
  • git format-patch, git send-email и похожие инструменты подставляют сводку в тему письма;
  • Рефлоги, локальная история, доступная по команде git reflog, предназначенная для восстановления при глупых ошибках, берет копию сводки
  • в gitk есть колонка для сводки;
  • GitHub использует сводку во множестве мест в интерфейсе.

Различие между сводкой/телом может показаться малозначительным, но это один из факторов, делающих историю Git удобной.

Вольный пересказ заметки A Note About Git Commit Messages.

Картинка взята отсюда.

3 комментария

avatar
А что такое «выступы» в данном случае? Можно примерчик?
0
avatar
Отступ, или абзацный отступ — это пробелы от начала строки.

  Абзацный отступ или «красная строка»
отступает от начала строки на несколько 
символов. Как в этом примере.


Выступ делает висячее начало строки, формируя левую границу абзаца правее начала первой строки.

- выступы формируют, например,
  списки с маркерами; иногда также 
  применяются выступы при верстке 
  текстов, требующих внимания 
  к структуре.
+1
Только зарегистрированные и авторизованные пользователи могут оставлять комментарии.