Git Commit сообщения: 50/72 Форматирование

Тим Поуп (Tim Pope) аргументирует конкретный стиль сообщения Git commit в своем блоге: http://www.tpope.net/node/106 .

Вот краткое изложение того, что он рекомендует:

• Первая строка не более 50 символов.
• Тогда пустая строка.
• Оставшийся текст должен быть заключен в 72 символа.

Его сообщение в блоге дает обоснование этих рекомендаций (для краткости я назову их «форматированием 50/72»):

• На практике некоторые инструменты обрабатывают первую строку как строку темы, а второй абзац - как тело (аналогично электронной почте).
• git log не обрабатывает перенос, поэтому трудно читать, если строки слишком длинные.
• git format-patch --stdout преобразует коммиты в электронную почту - так что для хорошей игры полезно, если ваши коммиты уже хорошо завернуты.

Пункт, который я хотел бы добавить, я думаю, что Тим согласился бы с:

• Подведение итогов вашей фиксации является хорошей практикой, присущей любой системе контроля версий. Это помогает другим (или вам позже) быстрее находить релевантные коммиты.

Итак, у меня есть пара углов на мой вопрос:

• Какая часть (примерно) из «лидеров мысли» или «опытных пользователей» Git придерживается стиля форматирования 50/72? Я спрашиваю об этом, потому что иногда новые пользователи не знают или не заботятся о практике сообщества.
• Для тех, кто не использует это форматирование, есть ли принципиальная причина для использования другого стиля форматирования? (Обратите внимание, что я ищу аргумент по существу, а не «я никогда не слышал об этом» или «мне все равно».)
• Эмпирически говоря, какой процент репозиториев Git охватывает этот стиль? (В случае, если кто-то хочет сделать анализ репозиториев GitHub… подсказка, подсказка.)

Моя точка зрения здесь не в том, чтобы рекомендовать стиль 50/72 или сбивать другие стили. (Чтобы быть открытым об этом, я предпочитаю это, но я открыт для других идей.) Я просто хочу получить обоснование того, почему люди любят или выступают против различных стилей сообщений Git commit. (Не стесняйтесь поднимать вопросы, которые также не были упомянуты.)

Что касается строки «резюме» (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, проект, который запустил git, если хотите, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , они не следуют правилу 50/72. Первая строка - 54 символа.

Я бы сказал, что последовательность имеет значение. Установите надлежащие средства идентификации пользователей, которые сделали коммиты (user.name, user.email - особенно во внутренних сетях. User @ OFFICE-1-PC-10293982811111 не является полезным контактным адресом). В зависимости от проекта сделайте соответствующую деталь доступной в коммите. Трудно сказать, что это должно быть; это могут быть задачи, выполненные в процессе разработки, а затем детали того, что изменилось.

Я не верю, что пользователи должны использовать git одним способом, потому что определенные интерфейсы для git обрабатывают коммиты определенным образом.

Я также должен отметить, что есть и другие способы найти коммиты. Для начала 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».