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

Question

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

Тим Поуп утверждает, что определенный стиль сообщения 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. (Не стесняйтесь поднимать вопросы, которые не были упомянуты, тоже.)

493 4

git

4 ответов:

Comments

Ничего не найдено.

mgalgs · Accepted Answer · 2017-10-12 17:49:20

относительно строки "резюме" (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:]]\+$.*$$//' | awk '{print length()}'
или текстовая гистограмма:
cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+$.*$$//' | awk '{lens[length()]++;} END {for (len in lens) print len, lens[len] }' | sort -n

leonbloy · Accepted Answer · 2016-09-08 22:27:21

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

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

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

Micah Zoltu · Accepted Answer · 2017-10-16 06:15:59

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

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

Я использую одну строку резюме в верхней части, и я пытаюсь сохранить его коротко, но я не ограничиваю себя произвольным числом. Было бы намного лучше, если бы 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 commit message, которую вы связали, никогда не писал программное обеспечение, которое будет потребляться широким спектром конечные пользователи на разных устройствах раньше (т. е. веб-сайт) поскольку на данный момент в эволюции программного обеспечения/вычислений хорошо известно, что хранение ваших данных с жестко закодированной информацией о представлении-это плохая идея, поскольку пользовательский опыт идет.

score 5 · Accepted Answer · 2010-02-18 18:24:16

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

взглянув на фиксацию ядра Linux, проект, который запустил git, если хотите, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bca476139d2ded86be146dae09b06e22548b67f3 они не следуют правилу 50/72. Первая строка-54 письмена.

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

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

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