Comments 115

Ну, а если хочется поговорить, то можно забить на ограничения (в сумме, а не в первой строке), добавляя Note:


fix: fixed bug with blablabla
Note: this fix if temporary blablabla long blablabla cause only 1st line will be displayed bold

На самом деле почему нет? Использую подобное для всяких мелких демок до 10к строк. Они всё равно в лучшем случае потом на сниппеты растаскиваются. И их читаю только я.


Коаны vim: Отчаяние медленного ученика

Мастер Вэ Ку доедал свой обед, когда ученик ворвался в его комнату и упал на колени к ногам Мастера. Слезы текли по лицу ученика и он был в полном отчаянии. Мастер Вэ Ку поставил горшок и спросил: «Что так расстроило тебя, о, юный ученик?»


«Учитель»,-сказал он, — «Я сдаюсь. Я никогда не постигну мастерства Vim! Я никогда не сумею постигнуть пути великих предков! Я никогда не осознаю суровой простоты и божественной пустоты совершенного применения Vim!»


«С чего это ты так решил?»


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


Мастер Вэ Ку встал. «Подойди со мной к окну»,-сказал он.


Студент поднялся с пола, проследовал за Мастером Вэ Ку к окну и посмотрел на соседский дом, что был через улицу. Через окно они вместе увидели молодого человека в костюме и галстуке, работавшего над документом.


«Что ты видишь?»,-спросил Мастер Вэ Ку. Студент наблюдал какое-то время:


«Этот молодой человек использует Microsoft Excel чтобы создать таблицу. Он заносит цифры руками в каждую ячейку. Он даже не знает как использовать формулы. Он делает заглавные буквы, нажимая Caps Lock, а затем нажимает её опять, когда всё готово. Он всё так медленно делает! Я не понимаю, как он может быть таким довольным?»


«Посмотрев на этого молодого человека, чем ты не доволен?»,-вернулся к разговору Мастер Вэ Ку.


И студент немедленно достиг просветления. Звали его Ку А и позднее он стал одним из великих Мастеров.


https://habr.com/post/176187/

Как и многие комментаторы из оригинальной статьи негодую с «imperative mood».
The commit message describes what the commit will do if published
Может это специфика именно en? У нас в команде без всяких оговоренных заранее конвенций пишут интуитивно «fixed» и т.п, т.к. воспринимаем это как уже свершившееся действие — баг исправлен.
Язык заголовков новостных статей не имеет ничего общего с тем, что написано в статье. Ни по применимости, ни по причинности. Сколько раз я встречаю попытку навязывания повелительного наклонения, столько раз вижу одно и то же невнятное объяснение про «The commit message describes what the commit will do if published». Обычно, если какой-то метод удобен, то его не нужно объяснять какими-то абсурдными вещами. Лично для меня очевидно, что этот метод написания неудобен, т.к. он абсолютно неинтуитивен и к нему нужно привыкать. С чего я должен к нему привыкать?

Та ссылка, что Вы привели, описывает вещи, которые очевидны: заголовок должен быть броским и коротким, именно поэтому там применяются вышеозначенные правила. Эти правила ясны и понятны (и не применяются в примерах хороших заголовков фиксаций в этой статье, кстати), правило повелительного наклонение непонятно и притянуто за уши.
Это не повелительное наклонение, а опущенное подлежащее во множественном числе.
This changes fix accidental crush — Эти изменения чинят внезапные падения.
Вот ещё один вариант, и кто так читает? Кроме Вас, естественно. Потому что видя фиксацию, люди обычно соотносят текст именно с ней, а не с изменениями. Именно поэтому чаще всего в природе встречаются два варианта: «[This commit] fixes blah blah» и «[This comment] fixed blah blah».

Ну и просто как добавка-придирка: git-commit это не набор изменений, чтобы говорить о них в тексте. git-commit это состояние репозитория, т.е. куда логичнее говорить о том, что в этой фиксации что-то было исправлено, либо же, что эта фиксация что-то исправляет.

Если же взять Ваш вариант, то получается:
Исправляют бла бла

Разве это не выглядит странно? Так в русском языке это ещё понять можно, что имеется в виду какое-то множественное число. Видя такой комментарий на английском, у меня закрадывается подозрение, что у человека просто плохо с языком. Только потом узнаешь, что это адепты какого-то нового стиля, который непонятно зачем и кому нужен.
Фиксация чего? Изменений. И комментарий касается именно этих изменений, разницы с предыдущим зафиксированным состоянием (независимо от того как там гит хранит историю у себя внутри). Ну да, кто-то комментирует «changes» и пишет «fix», кто-то «changeset» или «patсh» и пишет «fixes», а кто-то проделанную работу и пишет "I have fixed". По мне так лучше писать «fixes», чтобы не путать с повелительным наклонением и так как патчи существуют вне времени и могут применяться то тут, то там, помногу раз — это просто какая-то сущность, которая делает из произвольного состояния S состояние S+p.

Да, и мотивация с новостями одна и та же: вместить максимум смысла в минимум места.
Возможно. Я тоже раньше писал в прошедшем времени, и в императиве мне поначалу было странновато, но потом очень понравилось, когда «распробовал». Конечно, тут по большей части вопрос вкуса, но можно привести такие аргументы:

1. Коммит — это по сути информация об изменениях. Как-то правильнее, с моей точки зрения, ощущается вопрос «Что эти изменения делают» или «Что сделают», а не «Что эти изменения сделали». Т.к. это же не фиксированная точка в истории, коммиты можно переставлять местами, сливать, переносить в другие ветки и т.д.

2. Ну и так, уже менее серьезно — можно сэкономить два символа на окончании «ed» и некоторых неправильных глаголах :)
Коммит это именно что зафиксированная история, которую нельзя изменить. Можно сделать другой коммит зафиксировав другие изменения, переписав историю. Но от этого изначальный коммит не изменится.
Я имею в виду, что git-коммит — это же не снапшот репозитория. Это скорей инструкция, как привести код к какому-то виду, и если применить эту инструкцию к кодовой базе — получится, например, исправление бага или добавление фичи.
git-commit это как раз снапшот репозитория, а не инструкция к кодовой базе. git-commit не применяется, на него переключаются.
UFO landed and left these words here
Мне кажется 2 и есть причина. Повелительное наклонение позволяет сэкономить пару символов, а все остальное уже backwards reasoning.
Может это специфика именно en?

Это коллизия русского и английского языка. Потому что по-русски во фразе If applied, this commit will ... повелительное наклонение тоже не используется.
Там ответ на вопрос «Что сделает?».
В английском, видимо, эта форма и императив совпадают.
А в русском не совпадают ни по форме ни по смыслу (в данном контексте).
Перевод статьи с английского должен такие вещи учитывать, наверно.
Я думаю, на самом деле всё проще: просто в повелительном наклонении получается меньше всего служебных слов и изменения окончаний глаголов, текст короче и проще для понимания (глаголы — в начальной форме, а описание ситуации получается без лишних [дее]причастных оборотов). А описывать такой формат как «используйте глаголы в начальной форме, но не ставя перед ними to» и т.д. — это тоже длинно и сложнее для понимания.

Сам всегда писал и до сих пор пишу в прошедшем времени, но прочитав сравнение с Fossil пришёл к выводу, что для git более естественным форматов является именно продолжение "When applied, this commit will ...".


Насколько я понимаю, git изначально предполагал обмен изменениями через почтовые списки рассылки. То есть над проектом работает большое количество разработчиков, они присылают свои коммиты в виде писем в список рассылки. Условный Торвальдс смотрит рассылку, скажем, раз в день, и видит 10 разных патчей на одно состояние master`а, которые надо изучить и влить в общую историю.


При такой разработке "When applied, this commit will ..." выглядит логичнее. Во-первых, он больше подходит для письма — "смотрите, я написал такой патч, если вы его возьмёте, то он ...". Во-вторых, как вливать эти патчи в общую историю? На каждый из них делать ветку и merge? Тогда история превратится в серию "клубков" из мержей, по одному клубку на каждый день. Получается, нужен rebase. А если rebase и apply — это нормальный процесс вливания большинства патчей, то коммит уже нельзя считать чем-то совершённым. Коммит становится инструкцией по изменению кода, а когда и в каком порядке эти инструкции будут выполнены, заранее не известно.

никогда не видел, чтобы интеграция Git в IDE могла сравниться по простоте и возможностям с командной строкой (как только вы с ней разберетесь).

На 90% согласен, но merge поприятнее делать в красивом окошке IDEA.

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


Но в общем, да: поддержка Git в IDEA очень хороша, поэтому все чаще предпочитаю делать все из PyCharm, даже rebase.

Если у вас идет подряд с 10-к строк измененного текста, то как разбить на несколько логических коммитов?
Посему утверждение
поддержка Git в IDEA очень хороша
очень некоректно.
В самой IDEA с git есть ряд мелких и неприятных багов и недороботок.
10-к строк измененного текста, то как разбить на несколько логических коммитов?

Если не ошибаюсь, сегодня можно делать коммит не всего файла, а конкретных строк в IDEA (IDE) (чекбоксиками можно каждую нужную строку отметить). По крайней мере я этим пользуюсь — могу много правок по одному файлу разбить на несколько смысло-единых коммитов.
Я про
подряд с 10-к строк измененного текста
и этот блок мне нужно растащить по разным коммитам.
До конца не уверен, но подозреваю, что можно добиться путем "костыливания" временными разбиваниями массива строк на блоки.
Понимаю, что «на любителя» — прошу не кидать яйцами…
Не получится. Добавлени пустых строк только увеличит блок.
Пока приходится удалять «ненужные» блоки. Потом поочередно возвращать на место после каждого коммита.
Ctrl или Alt пока еще неумеют разбивать блок на строки при создании коммита.

В Intellij:
Правый клик на мега-коммит, 'Intereactively rebase from here'.
Там нужный мега-коммит помечаем как edit. Запускаем процесс.
Далее reset HEAD~ (лично мне проще это сделать из командной строки, но можно и через гуй сделать soft reset).
И дальше просто открываем диалог коммита и выбираем нужные куски/выключаем ненужные.
Или с помощью клавиатуры (если кусок один и большой) — просто удаляем блоки, которые не должны попасть в текущий коммит.


После коммита повторяем процесс.


Можно периодически кликать на редактируемый коммит в журнале (покуда он по-прежнему доступен) и делать compare with local, пока все изменения не будут учтены.


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

Т.е. делаем сначала мега коммит, а потом удаляем ненужное?
Хочется на этапе коммита.

image
По крайней мере в SourceTree всегда можно выбрать какие строки уйдут в комит, а какие останутся в unstaged. Полностью эмулируется поведение Interactive Staging.

Как это делать из Idea не знаю, она у меня только для read-only работы с гитом, чтобы посмотреть как менялась история.
Быстрое гугление подсказывает, что в 2018.1 версии наконец-то добавили partial commit. Но там как и на вашем скриншоте: комитить можно целиком chunk, выбрать отдельные строки нельзя. Поэтому пока лично я остаюсь на SourceTree.

jetbrain blog.
Ну галка справа от обведённой овалом области в строке 586 как раз и обозначает, что это будет включено в коммит и если её снять — то соответственно будет исключено из коммита.
Как уже написали — это новая фича.
Мне как раз нужно эту область в овале еще больше разделить на строки.

Вот уже никогда не понимал противопоставление GUI и command line. GUI позволяет исключить класс ошибок, связанный с неправильным набором команд, и упрощает многие действия. Command line даёт все возможности. Свой инструмент для своих задач.

Я бы сказал иначе. GUI — это как готовый автомобиль — сел сделал магический пас и поехал. А командная строка больше похожа на конструктор — слепил что надо на текущий момент и так же поехал.
Проблема в том что лепить каждый раз когда надо делать повторяющиеся вещи сильно надоедает, поэтому ленивые люди придумали автоматизацию через GUI. Командная строка она несколько больше мозгоёмкая чем GUI, сделать некоторую уникальную вещь можно только в командной строке, а изменить поведение GUI — практически невозможно или ещё более сложное мероприятие. Вот если бы GUI можно было легко расширять и изменять поведение некоторых казалось бы незыблемых вещей, тогда командная строка останется только для очень редких специфических действий. Недостаток IDE в том что невозможно полностью подстроить поведение под себя, некоторые вещи бывают так захардкожены что хоть стой хоть валяйся.
сделать некоторую уникальную вещь можно только в командной строке
Каждый раз, когда такое слышу, прошу примеров, но никогда их не получаю.

Можете привести пример ежедневной операции, которую нельзя сделать средствами GUI?
Уникальное <> ежедневное. Это может быть последовательность действий которая нужна один раз в год, и добавлять ещё одну кнопку в GUI нет никакого смысла. Например создание нового репозитория по своему шаблону и некоторыми начальными файлами(настроечными, конфигурационными, со своими уникальными дефайнами и т.п.) — один раз запустить скрипт, указав имя репозитория и всё.

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

Вот у нас во флоу есть такая задачка: перед вливанием таск-ветки в RC-ветку её нужно отребейзить на RC-ветку.
Это, конечно, не ежедневная задача, но пару раз в неделю — легко.


Вот так это делается через CLI:


git stash && mvn clean -P coverage && git co master && git pull && git co RC/1.3.0 && git pull && git co CBRPIS-1052 && git pull && git rebase RC/1.3.0 && git push -f && git co RC/1.3.0 && git merge --ff-only CBRPIS-1052 && git push && git br -d CBRPIS-1052 && git stash pop

Ну можно выкинуть зачистку проекта и проход через master:


git stash && git co RC/1.3.0 && git pull && git co CBRPIS-1052 && git pull && git rebase RC/1.3.0 && git push -f && git co RC/1.3.0 && git merge --ff-only CBRPIS-1052 && git push && git stash pop

Расскажите как это накликать в GUI :)

Да чего тут интересного-то?
Всего лишь ребейз ветки.
Но нужно:


  • отложить локальные незакоммиченные изменения (и вернуть их в конце назад)
  • обновить ту ветку на которую будем ребейзить
  • обновить ту ветку которую будем ребейзить (я иногда ребейз выполняю в отдельной папке чтобы не трогать текущую папку)
  • собственно прогнать ребейз
  • обновить таск-ветку на сервере
  • влить таск-ветку в RC-ветку и залить RC-ветку на сервер

Ничего сложного или интересного.
Но сделать это через GUI явно будет не так быстро и просто как через CLI.


И это даже не уникальная вещь, пример которой вы просили.
Самая обычная задачка.

Просто мы над текущим проектом больше 3-х лет работаем, но с такими задачами не сталкивались. Но и команда у нас небольшая.

Ну значит у вас флоу не предполагает ребейза, а если кто и делает ребейз веток, то это не часто.
У нас вот флоу такой — может они и не идеальный, но тут решение принимал не я.
Но и наш флоу, прямо скажем, не уникальный.

У консоли конечно преимущество в автоматизации. У GUI преимущество в наглядности и удобстве выполнения того, что требует внимания. Ну скажем если бы вы не знали точные названия веток, и нужные действия зависели от коммитов в них.


Интерактивный ребейз например делается так. Дифф, история, групповые отметки, всё рядом.

Ну в GUI вам названия веток всё равно нужны :)
Я не предлагаю отказываться от GUI, я абсолютно согласен с тем что многие вещи в GUI удобнее.
Просто некоторые вещи мне проще и быстрее сделать через CLI.

Абсолютно все эти команды есть в GUI: stash, pull, push, rebase, merge… и делается это достаточно просто и легко

Ну или вот есть задачка с которой я часто сталкиваюсь: пересортировка/объединение коммитов в ветке.
Через CLI это быстро: git stash && git rebase --interactive origin/RC/1.3.0 && git stash pop и там уже можно переставлять объединять коммиты как хочется.
Причём обычно это команда вызывает не один раз, а несколько: сначала переставить и проверить что оно отработало, потом уже объеденить.
Как это быстро делать через GUI я даже не скажу на вскидку.


А уж как разбить один коммит на несколько отдельных в GUI я вообще не знаю.
А такая задача встречается по нескольку раз в несколько месяцев.
В смысле — сначала собрал большой коммит и уже потом понял что лучше было разбить на несколько атомарных и вообще их пересортировать.

На сколько помню задача разбивания коммита в GUI реализована в SmartGit.
Все приведенные тут остальные использования git, где командная строка клеится через && некорректны.
С тем же успехом для такой операции можно написать скрипт и повесить его на кнопку (или вообще руками вызывать).
Вообще, использование GUI не обязывает отказываться от командной строки. Просто ускоряет и облегчает рутину.
Ну как мне видится именно к этому и призывают.
Когда мне говорят что православно постоянно писать git commit -a -m «Super comment»… или git push origin integration, вместо нажатия 1-2 кнопок это и есть отказ от GUI.
А мотивирую это тем что еще в CLI можно писать «git stash && git rebase --interactive origin/RC/1.3.0 && git stash pop».

Так что у всего должно быть свое время и место.

Я просто показывал что есть задачи которые удобнее выполнить в CLI.
Я нигде не призывал использовать только CLI.

Вот не знаю кому как, а мне быстрее написать git commit чем тянуться мышкой кликать кнопки. Это я не призываю всех быть как я, это я рассказываю что мне вот, например, это удобней, и что нас таких много
С помощью консоли переносить только определенные файлы в stage тоже удобней?
Попробуйте трекпоинт. Даже руки с клавиатуры убирать не нужно.
Все приведенные тут остальные использования git, где командная строка клеится через && некорректны.

А вот тут можно подробнее?
Если вы про скрипт — да, можно и так, но пока мне удобнее скопировать и вставить из файлика.
Или есть что-то более критичное?

Как написал выше, удобнее, IMHO, нажать несколько кнопок для простых операций, а для таких развесистых можно и && в CLI использовать.

Вообще, проблема CLI помимо небольшого замедления работы (набрать текст многим дольше чем нажать кнопку) это опечатки. При большом количестве веток и коммитов они обязательно закрадываются, и приходится переписывать строку. Например путаются I и l. Строчные и прописные буквы и прочее…
набрать текст многим дольше чем нажать кнопку

А код они как набирают? :)

Ну как сказать… Если код надо «набирать» то они не справляются. А если писать — там скорость не важна. IMHO лучше продумать дизайн и реализовать его, чем набирать быстро код.
Может я не прав, но что делать, я так всегда работаю… :)
Быстрая печать появляется сама, чисто с опытом. А если не появляется, значит вы просто, скорее всего, пишете мало кода.
В принципе да. Вспоминается сказка «Заяц и черепаха».
Код писать можно по разному. И понимание скорости у всех разное.
У меня скорость порядка 200 знаков/минуту и ритмичность 85%.
Но все гораздо хуже, когда вы пытаетесь с помощью IDE сделать коммит, слияние, перебазирование (rebase) или сложный анализ истории коммитов.

Юзаю GitExtensions — rebase там прекрасно работает. Анализ истории — не знаю, такое редко использую.

«Остап быстро вырвал его из рук Паниковского, говоря:
— Не делайте из еды культа.
После этого он съел огурец сам»

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

Ну, и PR можно комментировать чуть поподробнее, но упаси нас Боже от «граммар-наци»! (даже в софтверном смысле).

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


Если коммиты пишутся хорошо, то можно понять в чем дело по одному только взгляду на git blame. К сожалению, чаще всего это не так, так как многие пишут в commit message что попало, типа: "Fixed a bug" или "Refactoring" или "Today's work" или тому подобный бред, который вообще не помогает понять историю изменений.

Ну, а комментарии к коду данные люди писать отказываются? Все уже давным-давно решено за нас; не стоит надеяться на комментарии к комиттам! Нужна общая «код-дисциплина».

P.S. Мне и представлять не надо — так и работаю. И никак свое мнение после этого не меняю.

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


Системы контроля версий существуют в том числе и потому, что история изменений тоже имеет ценность.

Вы, ради примера, можете привести репу на гитхабе? Ну, «чиста поприкалываться ради»? (если не стыдно за проект)

У меня на GitHub только private-репозитории для проектов под NDA. За исключением пары pet projects и пары небольших клонов созданных для создания PR с исправлением какой-нибудь ерунды в open source библиотеках.


А что вы хотите увидеть? Пример моего плохого кода? Или наоборот, пример идеального?


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

Хотелось бы увидеть развернутые и оформленные, согласно статье выше, комментарии к вашим коммитам. (ну, «мужик сказал — мужик сделал»). Но, вы же понимаете, что если вы коммиттите один — то грош цена вашим «комментам», один хер, через пол-года забудете…

Я не говорил, что пишу коммиты именно так, как описано в статье. Я пишу осмысленные коммиты, как правило, это одна строка с таким описанием изменения, по которому можно понять, зачем оно было сделано, со ссылкой на соответствующий тикет в багтрекере. Напимер, Do not display QA Check button when evaluation hasn't been performed (#270).


Я не вижу смысла предоставлять какие-то пруфы, так как это не rocket science и требует, в общем-то, минимальных усилий от разработчика. Не сложнее, чем чистить зубы два раза в день, некий минимальный уровень гигиены.

Просто вставлю свои пять копеек, как пример «среднего» между совсем «бесполезными» и «идеальными» коммитами:
[IMPROVE]
- CJP (New boolean-sub-mode)
- Kernel (JS for the Scroll to element, logout-method)
[IMPROVE][REFACTOR]
- Modules


[ADD]
- Rewrited JSON, packages for modules of CMS
[IMPROVE][REFACTOR]
- Ejected sources from Modules to classes
- Log-subsystem
- Main class of AST


[IMPROVE][ADD]
- Microkernel [Subsystem for checking JS-errors]
[IMPROVE][REFACTOR]
- CJP
- Kernel
- Modules
- Moved subsystems from the Modules to standalone java classes [StepByStep, Pages]


Честно хочется делать лучше, но пока что не выходит. Впрочем до «bla-bla/fixed/today's work» все-таки не опускаюсь (немного больше нуля все-таки из истории понятно).

Ну и мои 5 копеек. Я пишу обычно идентификатор скоупа и пояснение что в нём произошло. Если это новый скоуп, то его краткое описание. Например:


$mol_textarea - multiline text editor
$conduit_article_editor: $mol_textarea for Content, style fixes
Не надо такие огромные коммиты. Имхо, надо в VCS добавить что-то вроде группового коммита и в нем описать группу мелких коммитов.
Малое прояснение — их тут я целых три привел, они разделены «пустыми строками».
Видимо визуально не сразу это понятно :)
Так-то я стараюсь по возможности не делать коммит с общим изменением более ~80-100 строк. Т.е. стремлюсь к атомарности. Разумеется это не всегда получается… к примеру, когда «глубокий рефакторинг» или «добавление сложной подсистемы из кучи файлов»
Я хоть и не immaculate, но полностью с ним согласен, грамотные коммит-логи это очень важно; у меня нередко больше времени уходит на написание лога, чем на собственно изменения в коде. По поводу «мужик сказал», вот пример моего коммита.

IMHO, слишком большие месседжи не есть хорошо, вот почему:


Как автор:


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

Как читатель:


  • то что мне важно, это что здесь и зачем сделано. всё остальное лишнее.
  • мне не важно когда и как появился исправленный баг, я это смогу и так выяснить, если будет такая необходимость, но зачастую это не важно.
  • использовать git log с отображением всего сообщения стаёт мучительным (попробуй найди нужный коммит, если каждый занимает около 2 экранов)
  • хорошо читаются структурированные короткие тезисы, монотонный текст же немного тяжелее читать.
В целом согласен с вами; обычно я просто стараюсь приблизительно следовать правилу «30% текста лога о том, что было изменено, 70% почему» (т.н. правило 30%-what-70%-why). Иногда коротко объяснить не получается (как и было в тот раз), но это же не повод писать маловразумительные комментарии типа «fix the build» или, как многие любят делать, тупо переводить commit diff на английский.

По моему опыту люди пишут комментарии отвечающие на вопрос "что тут происходит" в сложных местах и всяких хаках, а история комитов отвечает на вопрос "зачем".

Но стоит кому-то перенести код из одного места в другое и git blame превращается в тыкву. Как бы красиво мы ни писали комментарии к коммитам, они с весьма не нулевой вероятностью потеряются при просмотре конкретного файла. Красивая идея разбивающаяся о несовершенство реализации. Поэтому единственная полезная функция комментариев к коммитам — семантическая идентификация этих самых коммитов в истории изменений.

Если переносить файл командой git mv, то ничего не потеряется. Если функцию переносить из файла в файл, то в той же IDEA можно достаточно легко отследить ее миграцию используя функцию "Annotate previous version."


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


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


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

UFO landed and left these words here

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


Контр-примеры можно найти к чему угодно в этой жизни. И любую практику можно довести до абсурда. Истина, как всегда, где-то посередине.


Что касается миграции, то я в свое время работал над достаточно большим проектом, который за 10 лет совершил миграции Subversion -> Mercurial -> Git (непонятно, зачем был нужен последний шаг, но не я принимал такие решения). Тем не менее, вся история осталась доступна, начиная с первого коммита.

Но стоит кому-то перенести код из одного места в другое, и git blame превращается в тыкву.
Не обязательно, просто переносить надо умеючи, и думать про историю изменений. Даже когда между VCS'ками переезжаешь, это вполне реально — к примеру, FreeBSD, когда переезжала с CVS на Subversion, всю многолетнюю историю изменений сохранила.

Справедливости ради, эта проблема в некотором смысле имеет место, когда ты, условно, уехал на месяц в тайгу, предварительно импортнув код из корпоративной сабверсии в локальный hg, и сидишь себе такой, hack-hack-hack без интернета. Потом, по возвращению, приходится всё это как-то рибейзить и группировать мелкие коммиты перед чекином в основной репозиторий. Но это частности и, в общем, понятно, как их разруливать.
Поэтому единственная полезная функция комментариев к коммитам — семантическая идентификация этих самых коммитов в истории изменений.
Не согласен. Коммит-логи — такая же неотъемлемая часть проекта, как и сам код и комментарии к нему, и требования к качеству оных совершенно аналогичные.
Я скажу так: лучше комментируйте свой код, пишите четкие комментарии по делу

Возьмем например этот коммит: "Fix a bug when having more than one named handler per message subscriber". Изменено 2 файла в нескольких местах. Вы в каждом месте будете один и тот же комментарий писать? А если 10 файлов изменено?

UFO landed and left these words here
Комменты к коду и комменты к коммитам совершенно разные вещи, и несут совершенно разные смысл. Коммит это изменение состояния проекта, и коммент описывает смысл этого изменения. А комменты к коду просто показывают что этот код делает
Я против длинных простыней объяснений в коммитах.
Наверняка есть Jira (или аналог), в котором описана задача, со скриншотами, коментариями и обсуждениями. Достаточно в начале каждого коммита писать номер задачи и краткую причину.
UFO landed and left these words here
В одном старом проекте перешли с TFS на GIT, и все коммиты стали пустым местом (реальный случай). И что?

Плохо переходили.
Я когда переходил с SVN на GIT сохранил всю историю коммитов с комментариями авторами и датами.

О, а расскажите как, я скину, тому кто делал переход.

А про «А потом команда перешла с Jira на аналог и все ваши номера стали пустым местом» можно также ответить — плохо переходили, раз не смогли сохранить номера.
А про «А потом команда перешла с Jira на аналог и все ваши номера стали пустым местом» можно также ответить — плохо переходили, раз не смогли сохранить номера.

Можно, но тут сложнее.


Я когда переходил с SVN на GIT сохранил всю историю коммитов с комментариями авторами и датами.

Заметьте что тут я не говорил про идентификаторы коммитов — их невозможно сохранить.


Та же фигня будет и с тикетами:


  • сохранить сами тикеты можно в 99% случаев
    Куча примеров миграции с Google Code на Github тому подтверждение
  • сохранить автора тикета уже сложнее — для начала такого пользователя просто может не быть на момент миграции или вообще в организационной структуре
    Автор коммита же может быть хоть Дэвид блэйн
  • сохранить комментарии тоже скорее всего получится
  • сохранить автора/дату комментария уже сложнее — автора по причине выше, а дату не все системы позволят изменить задним числом через API, а в БД залесть можно только на self-hosted вариантах
  • а вот идентификатор тикета сохранить почти наверняка не выйдёт из-за специфики нумерации в исходной и целевой системах
    Jira требует указание уникального префикса и потом номера уникального в рамках префикса
    У кого-то номера уникальны в рамках всей системы
    И т.д. и т.п.

Самое важное в последнем пункте — в коммите ссылаются на идентификатор тикета, а вот идентификатор тикета сохранить очень сложно.
И в результате нумерация или:


  • съедет на N цифр с какую-то сторону (по определённого тикета, а потом опять будет совпадать — вот веселье-то)
  • вовсе не будет никогда совпадать (переехали с Jira на Github)
О, а расскажите как, я скину, тому кто делал переход.

7 (семь!, боже как давно) лет назад я сделал это примерно так: https://github.com/valery1707/docs-linux/blob/master/vcs/git-svn-convert.txt


С тех пор много воды утекло — что-то могло и измениться, но не думаю что сейчас невозможно нормально мигрировать с TFS на GIT/HG/Whatever — скорее всего плохо искали.
Более того, я уверен что вам историю коммитов можно даже и восстановить, если остался доступ к TFS: сначала мигрировать корректно, а потом наложить все коммиты что вы создали позднее.

Мой вариант: README.md в проекте, а уже в нём — подробное описание что и как, для каждого комммита.

А почему в README.md?
Как по мне, там нужны общая информация о проекте: что зачем и почему, и уж точно там не место описаниям всех коммитов.
Ладно бы ещё CHANGELOG, но и там не каждый коммит подробно расписывают, а ведут лог изменений.

Название не принципиально. md — потому что маркдаун (какое-то минимальное оформление надо, видимое в IDE, но не HTML или BB-коды же).

общая информация о проекте

Нет, не о проекте, а именно об этой ветке. Да, ошибся — речь не о коммите (хотя и это не помешает).
CHANGELOG

Сколько у вас коммитов на ветку? У меня — десятки. А сколько веток на хотя бы минорную версию продукта?


P.S. Я о внутренней кухне, а не о том, что лежит в публичном доступе :)

Проблема в том что в БагТрекере не всегда ясно зачем нужны эти изменения — в лучшем случае из-за чего. А это не одно и тоже.


Очень часто баз описан как Стоппер! Ничего не работает - NullPointerException.
Да, можно и в тикете написать из-за чего происходит ошибка и зачем мы вносим изменения.


Но есть вторая проблема: отделение изменений от причин их создания.
Да, есть трекер в котором разработчик возможно это описал.
Но нужно ещё попасть из коммита в трекер — скопировать ID тикете, открыть трекер, найти там тикет.
Потом среди кучи комментариев понять какой из них описывает собственно изменения, а какие просто описывают поиск ошибки и обсуждают меню корпоративного обеда.


А ещё часто бывает когда в рамках одного тикете решаются несколько разных проблем. Есть тикет Не работает экспорт файла: сначала там были ошибки в формате, потом NPE в паре мест, потом мы файл не создавали по какой-то причине, а потом оказалось что ожидался XML внутри ZIP, а мы сделали JSON.
Тикет один, коммитов много, причина каждого коммита хорошо если вообще понятна из комментариев к тикету.


Другая ситуация: Тикет один и даже понятный и лаконичный.
Но коммитов много, так как задача большая и много атомарных коммитов лучше через изменение 50% системы с одним коммитом Так нужно для тикета #13257.


Так что уверен что баг-трекер не панацея и нормальные комментарии к коммитам необходимы.

Эммм…
У нас баги описывают правильно, с шагами, что ожидалось и что получилось. Формулировок «Ничего не работает» не пишут.

Я повторю — «Достаточно в начале каждого коммита писать номер задачи и краткую причину.»

Написать только номер задачи — нет.
Написать одинаковую причину в нескольких коммитах «Так нужно для тикета #13257» — нет.
Обсуждать в Jira меню корпоративного обеда — нет.
В рамках одного тикета решаются несколько разных проблем — если надо разбейте тикет, если надо разбейте по коммиту на проблему (в каждом будет краткое описание отдельной проблемы).

Писать кучу текста в коммит и дублировать в таск-трекер — вот такого не должно быть. Надо выбрать что-то одно в качестве первичного источника информации, а во втором делать ссылку. У на это таск-трекер. Если у вас это коммиты, ну ок, хотя лично мне было бы неудобно, наверно.
У нас баги описывают правильно, с шагами, что ожидалось и что получилось. Формулировок «Ничего не работает» не пишут.

Вам повезло. Вот правда.


Разница между тикетом и коммитом состоит в том что


  • тикет может создать много кто (внутренний тестер, внешний тестер, разработчик, аналитик, заказчик) и не от всех можно ожидать (тем более требовать) полноценного описания
  • коммит пишет разработчик — вот от него нужно ожидать (как минимум!) возможность описать зачем он сделал эти изменения
  • в тикете может быть много обсуждений бага, даже корректно описанного (шаги воспроизведения, окружение, выбор решения проблемы и прочее (про меню это была гипербола, конечно))
  • в коммите описывается конечный результат
  • в тикете не всю информацию стоит раскрывать (показывать заказчику что у нас была огромная дырень в безопасности, которую мы закроем при обновлении через 2 месяца — вот он обрадуется прямо сейчас, ага)
  • коммит внутренний ресурс (обычно) и там можно писать всё что угодно

Писать кучу текста в коммит и дублировать в таск-трекер — вот такого не должно быть.

Я и не говорил про дублирование.
В тикете не всегда обязательно писать полное описание причин ошибки и методов её устранения.


У на это таск-трекер. Если у вас это коммиты, ну ок, хотя лично мне было бы неудобно, наверно.

Удобство — понятие относительное.
Мне вот удобно всё видеть в коммитах потому что я могу прямо из среды разработки в offline в отпуске на Багамах в туалете понять что и зачем происходили в классе. Да хоть из консоли, лишь бы исходники были.
А вам исходников не достаточно — нужен доступ ещё и к таск-трекеру. Причём не только сетевой доступ, но и организационный. Ну ок.

в тикете не всю информацию стоит раскрывать (показывать заказчику что у нас была огромная дырень в безопасности, которую мы закроем при обновлении через 2 месяца — вот он обрадуется прямо сейчас, ага)

Ну это ваша специфика, так же как и возможность разработки offline.

У нас иначе, поэтому и подход другой.
Не забывайте про Open Source проекты, где частенько случается, что никаких описаний задач нет, иногда и ишью тоже.

Полагаю, когда работа идет в команте на постоянной основе, с ишью-трекером и т.п., то как правило можно ограничиться заголовком и, когда уместно, парой строк в теле. Но если их писать по вышеуказанным правилам, смотреть в репозиторий и ориентироваться в нем будет гораздо приятней, как по мне.
Но если счет коммитов идет на десятки или сотни тысяч то оно точно стоит того?
Не представляю ситуацию где описание коммита даст больше понимания чем сам код.
Вы, видимо, просто не принимали участие в крупном опенсорсном проекте с большой историей, где число коммитов как раз сотни тысяч, разработчиков сотни, все с разной квалификацией, отношением к коду и представлением о прекрасном, и которые приходят и уходят (т.е. тупо спросить, как обычно, коллегу «Вася, чего это ты тут наговнокодил в позапрошлом году?» получается далеко не всегда).
На счет повелительного наклонения.
Автор предлагает отвечать на вопрос «что сделать?»:
— Обновить webpack до версии 4
— Покрыть типами экшены
— Реализовать удаление новости

Но в истории или changelog-е, мне кажется, будет лучше если отвечать на вопрос «что сделано?»:
— Обновлен webpack до версии 4
— Покрыты типами экшены
— Реализовано удаление новости
Clean your room (приберись в комнате)
Close the door (закрой дверь)

Я бы сказал, в английском это смотрится более естественно, так как там меньше разных словоформ. Инфинитив без to это самая нейтральная форма. У нас нейтральной считается обезличенные "добавлено", "изменено".


Если переводить на русский, то лучше тоже инфинитивом, ну как команды типа "Стоять!" — "Прибраться в комнате", "Закрыть дверь", "Смержить ветку 'myfeature'". Чтобы можно было мысленно добавить "Надо" или "Надо было".

Ладно автор из 2014-го года. Но в обсуждении перевода столько разных самостийных стилей написания комментариев к коммитам, и при этом ни одного упоминания Conventional Commits.
у себя придерживаюсь стиля распространенного во многих апачевских проектах, например spark:

[mandatory ticket name][optional subsystem] description

[SPARK-6237][NETWORK] Network-layer changes to allow stream upload.
[SPARK-18073][DOCS][WIP] Migrate wiki to spark.apache.org web site

дальше в самом комит сообщении можно развернуть более подробно, но уже по заголовку есть
  1. отсылка к багтрекеру с обсждением бага
  2. подсказка какие компоненты затрагивались (удобно для больших проектов)
  3. краткое описание, что сделано


Квадратные скобки упрощают парсинг автоматическими утилитами.
Кто в 2018 делает коммит без соответствующего тикета?

Указываешь номер тикета и кратко что это, кому интересно — сам в трекере найдет все спеки и обсуждение.
Странно, но никто не упомянул, что данные правила частично совпадают со «стандартом» питона (PEP 8, PEP 257). Частично — в данных документах рекомендуется ставить точку в конце первой строчки Docstring.
В русском языке повелительное наклонение принимает форму заклинания, наговора, усиливающего вносимое изменение, — «Исправь то», «Сделай сё». А вместо точки в конце лучше ставить 'X', — «скрестить пальцы».
Only those users with full accounts are able to leave comments. Log in, please.