Многострочный комментарий в git commit

https://www.google.com/search?q=git+commit+message+new+line Первая ссылка. Даже переходить не надо.

Просто добавляй ‘\n’ между «строками».

После первой строки нужно два \n чтобы отделить заголовок сообщения или это необязательно?

Да, лучше отделить. Ту строку я просто для примера дал.

Следует еще помнить, что некоторые системы, использующие git (типа bitbucket, gitlab и проч.) видя многострочный заголовок иногда выводят только первую строку во всех своих описаниях.

Bitbucket при выводе списка коммитов в дереве выкидывает все переносы и делает … если не влезает в одну строку. При открытии коммита всё ок с переносами и форматированием.

Не надо так делать.

Многострочные комментарии ужасно выглядят в ИДЕ и графических тулзах, сбивают с толку и вообще не гуд. Если вам есть много что сказать по поводу коммита, то скорее всего вы неправильно его готовите. Обычно, гитовый коммит соответсвует тикету, а не эпику. Если тикет объемный то имеет смысл коммитить логически связанные изменения и много текста писать не о чем. Типа «пофиксили баг с краказябрами в таком-то контроле». В любом случае, разумно в комментарии давать ID тикета, тогда если кому-то понадобится подробная информация об изменениях он найдёт соответстующий тикет и пулл реквест, вот там расписывайте всё в красках

ID билета выглядит плохо, сбивает с толку и вообще нехорошо. Особенно если и билетов то никаких нет.

Ага, вместо того чтобы прочитать основную суть коммита прямо в редакторе – идти искать тикет. Особенно весело, если в какой-то момент компания переезжает с jira на что-нибудь ещё и всё это добро теряется.

Жира - самая большая база знаний с историей компании/проекта, включая обсуждения, идеи, эксперименты, как пришли к тому или иному решению, бизнес целями и прочим, поэтому плохая та компания которая съезжает с жиры и не сохраняет историю.

Ну пусть тогда переезжает на жиру с чего-то ещё. Суть не меняется – commit message вида «пофиксил багу #20562» это такой же говнокод, как отсутствие отступов. Особенно когда смотришь на историю изменений в режиме oneline. Для этого есть git trailer, т.е. описываешь суть изменений и на последней строчке ставишь «Closes: $NUMBER».

Ссылка в описании коммита станет нерабочей.

У меня был только однажды опыт переезда с jira, но то было на самописный трекер в котором было похожее наименование тикетов и специально сохранена совместимость с урлами жиры.

Ну и не обязательно гасить жиру, можно оставить read-only инстанс.

В любом случае из краткого описани коммита лучше, когда сразу понятно, что это.

Суть не меняется – commit message вида «пофиксил багу #20562» это такой же говнокод, как отсутствие отступов.

Из каких конкретно слов моего комментария сделан вывод, что надо писать «пофиксил багу #20562»?

Из каких конкретно слов моего комментария сделан вывод, что надо писать «пофиксил багу #20562»?

Из «Многострочные комментарии ужасно выглядят в [моей] ИДЕ» и «разумно в комментарии давать ID тикета» следует, что вы предлагаете писать ID тикета в первой строке.

Я предлагаю (да нафиг, это не я предлагаю, это стандартная практика) писать в комментарии к коммиту краткое, но ёмкое содержание изменений, а за подробностями отправлять в пулл-реквест и Джиру. Краткое но ёмкое, вовсе не означает «пофиксил багу #20562». Если человек не полный дебил, он так не напишет. В 72 буквы латиницы рекомендующиеся под строку коммита в гайдлайнах можно уместить много информации включая и ИД задачи. Пример: «J-32525: Add HTTP-403 error handler to avoid unexpected exceptions during maintenance». Вот это же не «пофиксил багу», правильно? Всю информацию о проблеме в сообщение коммита всё равно не вместить. Где, когда и сколько раз воспроизводилась, что было в логах, обсуждения, предложнеия - это всё в Джире или Тим Сити или где-то там ещё. Научитесь кратко излагать свои мысли, коллеги.

А я про то, что «Многострочные комментарии ужасно выглядят в ИДЕ» – проблемы исключительно твоей IDE. И лучше иметь многострочное описание в коммите, чем не иметь. Мне вот удобнее в magit читать, чем лезть куда-то в джиру, или ещё хуже – пулл реквест.

И классический гайдлайн гит сообщений выглядит как:

component: verb something

Describe unobvious things (fills pull request description)..

Change-Id: $HASH // persists cherry-picks and rebases
Closes: JIRA-123
Reported-by: gena@
Reviewed-by: vasya@
Tested-by: masha@

PROJ-777: [Component] Title. The truth is out there

Проще и меньше намного дубликации информации из багтрекера. Вариант добавлять ссылку на документ в docs из текущего репозитория с полным описанием.

Кратко по недостаткам ИМХО:

1. Первой строчкой компонент - банально one-line git log будет вам показывать одинаковые коммиты.

2. Closes - не нужен, можно префиксом к комменту коммита.

3. Reported/Reviewed/Tested - это не git, дублирование Jira/Redmine. В истории статуса в Jira есть полная информация об этом.

4. gena, masha - кто все эти люди? у них точно доступ к git есть?

5. Как вы собираетесь графики и диаграммы добавлять в многострочный комментарий? Иногда кучу информации нужно представить, чтобы объяснить, что новое решение на 3-4% производительнее старого. Добавить блоксхемы, чтобы джун и миддл осилили решение и не напортачили.

0. Не проще эти «PROJ-777:» превращают oneline logs в нечитабельное месиво. Сначала должна идти информация для человека, потом для машины.
1. У меня компонент как у вас, только короче на 1 символ;
2. Issue/Closes нужен хотя бы для того, чтобы та же Jira автоматом связала коммит к тикетом, и вставила ссылку на гитлаб/etc;
3. Reported/Reviewed/Tested – проделали работу наравне с Author: и Commit:, чем заслужили упоминания в git log. Потом можно, например, сделать git grep и увидеть, кто над чем работал.
4. gena, masha - кто все эти люди? у них точно доступ к git есть? – а нужен? Коммиттер отвечает за то, что коммитит.
5. Как вы собираетесь графики и диаграммы добавлять в многострочный комментарий – не собираюсь, это лишнее. Но 3-5 строчек написать (продублировать из джиры) лучше прямо в git.

А я про то, что «Многострочные комментарии ужасно выглядят в ИДЕ»

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

Вот с чем я категорически несогласен, это с тем, что ты из моего сообщения достал два слова, которые тебе понравились, ты их слепил в одно словосочетания, довел до абсурда и принялся опровергать. Так не дискутируют приличные люди, это педерастия