Git Commit Messages: 50/72 Форматирование

Ответ 1

Что касается "итоговой" строки (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

Ответ 2

Относительно "лидеров мысли": Линус решительно выступает за перенос строк для полного сообщения о фиксации:

мы используем 72-символьные столбцы для обертывания слов, за исключением цитируемых материал, который имеет определенный формат линии

Исключения относятся в основном к тексту "непрозаика", то есть к тексту, который не был введен человеком для коммита - например, сообщения об ошибках компилятора.

Ответ 3

Разделение презентаций и данных приводит сюда мои сообщения о фиксации.

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

Я использую одну сводную строку вверху, и я стараюсь держать ее коротким, но я не ограничиваю себя произвольным числом. Было бы намного лучше, если бы 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 throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

Вот что выглядит в средстве просмотра, которое мягко обертывает текст.

Это сводная строка, старайтесь держать ее коротким и заканчивать разрывом строки.

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

Два разрыва строки разделяют эти две мысли. Пользователь может читать это на телефоне или на широкоэкранном мониторе. Вы когда-нибудь пробовали читать 72 символа, обернутого текстом на устройстве, которое отображает только 60 символов? Это поистине болезненный опыт. Кроме того, вступительное предложение этого параграфа (при условии формата стиля эссе) должно быть введено в абзац, поэтому, если инструмент выбирает его, он может не автоматически обернуть и позволить вам просто увидеть начало каждого абзаца. Опять же, это не инструмент презентации, а не я (случайный автор в какой-то момент истории), чтобы попытаться заставить мое конкретное форматирование всех остальных горло.

Как пример, вот список точек:
  * Пункт 1.
  * Пункт 2.
  * Пункт 3.

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

Ответ 4

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

Взглянув на 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 - особенно во внутренних сетях. Пользователь @OFFICE-1-PC-10293982811111 не является полезным контактным адресом). В зависимости от проекта, сделайте соответствующие детали доступными в фиксации. Трудно сказать, что это должно быть; это могут быть задачи, завершенные в процессе разработки, а затем детали того, что изменилось.

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

Я также должен отметить, что есть другие способы найти коммиты. Для начала git diff расскажет вам, что изменилось. Вы также можете делать такие вещи, как git log --pretty=format:'%T %cN %ce', чтобы форматировать параметры git log.

Ответ 5

Максимальная рекомендуемая длина заголовка действительно 50?

Я верил в это годами, но, как я только что заметил, документация "git commit" на самом деле гласит

$ git help commit | grep -C 1 50
      Though not required, its 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".