Как следует писать комментарии к коммитам

https://chris.beams.io/posts/git-commit/
  • Перевод


Предисловие от переводчика


На протяжении многих лет разработки ПО, будучи участником многих команд, работая с разными хорошими и опытными людьми, я часто наблюдал (да и чего греха таить, до определенного момента — создавал) одну и ту же проблему — тотальный бардак в репозитории. Каждый писал комментарии к коммитам в своем стиле (и хорошо, если постоянно в одном); половина комментариев была бесполезна (из разряда "это мост"), половина оставшейся половины — едва понятна.

И вот в один прекрасный момент я увидел данную статью, до перевода которой у меня наконец дошли руки. Всего 7 простых и коротких правил, и — о чудо — смотреть на историю коммитов стало не только полезно, но и приятно. Ничего революционного, все довольно очевидно, но сформулировано и резюмировано просто отлично.

Хочу заметить, что это статья 2014 года. Какие-то не сильно релевантные вещи, упоминаемые автором, могли потерять актуальность, но суть статьи — ничуть.

Введение: чем важны хорошие комментарии


Если вы заглянете в случайный Git-репозиторий, то, скорее всего, обнаружите, что в истории коммитов там в какой-то мере бардак. Например, взгляните на эти перлы из того времени, когда я начинал коммитить в репозиторий Spring:
$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"

e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishing
Жуть. Сравните с этими, более свежими, коммитами в том же репозитории:
$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"

5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage
Какой вариант вы бы предпочли?

Первые разнятся по длине и стилю, вторые — лаконичные и однородные.
Первое получается само собой, второе пишется осознанно.

И хотя история коммитов многих репозиториев выглядит подобно первому варианту, есть исключения. Отличные примеры — ядро Linux и сам Git. Посмотрите также на Spring Boot или любой другой репозиторий, которым занимается Tim Pope.

Участники этих проектов знают, что хорошо написанный комментарий к коммиту — это лучший способ рассказать о контексте сделанных изменений другим разработчикам (а также самим себе — в будущем). Различия в ревизиях показывают, что изменилось, но только комментарий может внятно объяснить — почему. Peter Hutterer хорошо сказал об этом:
Восстановление обстоятельств написания кода — расточительная трата времени. Мы не можем полностью ее избежать, поэтому наши усилия должны быть сосредоточены на минимизации этих затрат. Именно для этого и нужны комментарии к коммитам. Следовательно, они показывают, хорошо ли программист работает в команде.
Если вы не особо задумывались о том, каким должен быть первоклассный комментарий коммита — вероятно, вы не слишком часто использовали git log и похожие инструменты. Тут замкнутый круг: так как история коммитов неструктурированная и разнородная, ей не пользуются и не уделяют внимания. А из-за того, что ей не пользуются и не уделяют внимания, она остается неструктурированной и разнородной.

Но хорошо оформленная история репозитория — вещь прекрасная и полезная. Оживают команды git blame, revert, rebase, log, shortlog и прочие. Появляется смысл просматривать чужие коммиты и пулл-реквесты, и, внезапно, при этом теперь не требуется помощь их авторов. Разобраться, почему что-то случилось [в коде] месяцы или годы назад становится не только возможно, но и удобно.

Долгосрочный успех проекта зависит (помимо всего прочего) от того, насколько его удобно поддерживать, а история коммитов — один из самых мощных инструментов мейнтенера. Стоит потратить время на то, чтобы научиться сохранять в ней порядок. Сначала это может причинять некоторые неудобства, но потом войдет в привычку и, в конце концов, станет источником гордости и продуктивной работы всех участников.

Эта статья затрагивает лишь самую базовую составляющую ведения добротной истории, а именно — как следует писать комментарий к отдельному коммиту. Есть и другие важные вещи, например, объединение коммитов, которые здесь не рассматриваются.

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

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

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

Содержимое. Какая именно информация должна (если вообще должна) содержаться в теле комментария? А чего там не должно быть?

Метаданные. Как следует ссылаться на ID задач, номера пулл-реквестов и т.д.?

К счастью, уже существуют соглашения о написании содержательного комментария. На самом деле, они частично вытекают из того, как работают некоторые команды Git. Вам не нужно изобретать велосипед. Просто следуйте семи правилам ниже — и будете на шаг ближе к истории коммитов, достойной профессионала.

Семь правил классного комментария к коммиту


Помните: Все это уже было сказано раньше.
  1. Отделяйте заголовок от тела пустой строкой
  2. Ограничивайте заголовок 50 символами
  3. Пишите заголовок с заглавной буквы
  4. Не ставьте точку в конце заголовка
  5. Используйте повелительное наклонение в заголовке
  6. Переходите на следующую строку в теле на 72 символах
  7. В теле отвечайте на вопросы что и почему, а не как

Например:
Резюмируйте изменения в 50 символах или меньше

Тут объясните их более детально, если необходимо. Выполняйте
переносы строк примерно на 72 символах. В некоторых ситуациях
первая строка комментания считается его заголовком, а все 
остальное - телом. Крайне важно отделять оделять одно от другого
пустой строкой (если у сообщения вообще есть тело, конечно);
различные инструменты типа `log`, `shortlog`и `rebase` не поймут
вас, если заголовк и тело не будут отделены.

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

Параграфы разделяются пустыми строками.

 - Можно делать маркированные списки

 - Обычно в качестве маркера списка используется звездочка или 
   тире с пробелом перед ними; но тут есть разные соглашения

Если у вас есть баг-трекер [или система управления проектами],
поместите ссылки на задачи в конце текста таким образом:

Решено: #123
Смотрите также: #456, #789

Оригинал
Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789



1. Отделяйте заголовок от тела пустой строкой


Из мануала к команде git commit:
Хотя это не обязательно, но хорошей идеей будет начинать комментарий к коммиту с одной короткой (менее 50 символов) строки, обобщающей сделанные изменения, затем пустая строка и затем более подробное описание. Текст до первой пустой строки в комментарии считается заголовком коммита и используется в разных командах Git. Например, Git-format-patch(1) превращает коммит в email; команда использует заголовок коммита для темы письма и остальной текст — для тела письма.
Во-первых, не каждый коммит требует заполнения и заголовка, и тела. Иногда одной строчки вполне достаточно, особенно когда изменения настолько малы, что никакой дополнительной информации о них не требуется. Например:
Fix typo in introduction to user guide
Сказанного достаточно; если пользователь захочет узнать, что именно за опечатка была исправлена, он может просто посмотреть на сами изменения, используя git show или git diff, или git log -p.

Если вы коммитите что-то в этом роде с помощью командной строки, удобно будет использовать опцию -m для git commit:
$ git commit -m "Fix typo in introduction to user guide"

Однако, когда коммит заслуживает некоторых объяснений и описания ситуации, вам нужно записать их в тело комментария. Например:
Derezz the master control program

MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.

Комментарии, у которых есть тело, не так удобно писать с помощью опции -m. Будет лучше использовать для этого текстовый редактор. Если вы еще не настроили редактор для использования с Git, прочтите этот раздел книги Pro Git.

В любом случае, разделение заголовка и тела комментария окупится при просмотре лога. Вот полная запись о коммите:
$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date:   Fri Jan 01 00:00:00 1982 -0200

 Derezz the master control program

 MCP turned out to be evil and had become intent on world domination.
 This commit throws Tron's disc into MCP (causing its deresolution)
 and turns it back into a chess game.

А вот команда git log --oneline, которая выводит только строку заголовка:
$ git log --oneline
42e769 Derezz the master control program

Или git shortlog, которая группирует коммиты по автору, опять же, для краткости показывает только заголовок:
$ git shortlog
Kevin Flynn (1):
      Derezz the master control program

Alan Bradley (1):
      Introduce security program "Tron"

Ed Dillinger (3):
      Rename chess program to "MCP"
      Modify chess program
      Upgrade chess program

Walter Gibbs (1):
      Introduce protoype chess program

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

2. Ограничивайте заголовок 50 символами


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

Интерфейс GitHub’а поностью поддерживает эти соглашения. Он предупредит вас, если вы выйдете за пределы лимита в 50 символов:


И обрежет все заголовки длиннее 72 символов, подставив троеточие:


Так что стремитесь к 50 символам, но учтите, что 72 — это строгое ограничение.

3. Пишите заголовок с заглавной буквы


Тут все просто. Начинайте все заголовки с заглавной буквы.

Например:

  • Accelerate to 88 miles per hour

Вместо:
  • accelerate to 88 miles per hour


4. Не ставьте точку в конце заголовка


В ней нет никакой необходимости. Кроме того, каждый символ на счету, когда мы пытаемся уложиться в 50.

Например:

  • Open the pod bay doors

Вместо:
  • Open the pod bay doors.


5. Используйте повелительное наклонение в заголовке


Повелительное наклонение буквально означает: форма глагола, выражающая волеизъявления (приказ, просьбу или совет). Несколько примеров:

  • Clean your room (приберись в комнате)
  • Close the door (закрой дверь)
  • Take out the trash (вынеси мусор)

Каждое из семи правил, о которых вы сейчас читаете, написано в повелительном наклонении («Переходите на следующую строку в теле на 72 символах» и т.д.).

Эта форма может звучать немного грубо, и поэтому не так часто используется [в английском языке — прим. пер.]. Но она идеально подходит для заголовка коммита. Одна из причин — тот факт, что сам Git использует повелительное наклонение, когда создает коммиты от вашего имени.
Например, при использовании git merge по умолчанию добавится такое сообщение:
Merge branch 'myfeature'

А при использовании git revert:
Revert "Add the thing with the stuff"
	
This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

Или при клике на кнопку «Merge» в интерфейсе пулл-реквеста в GitHub:
Merge pull request #123 from someuser/somebranch

Так что, когда вы пишете собственные сообщения к коммиту в повелительном наклонении, вы следуете правилам, заложенным в сам Git. Например:

  • Refactor subsystem X for readability
  • Update getting started documentation
  • Remove deprecated methods
  • Release version 1.0.0

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

  • Fixed bug with Y
  • Changing behavior of X

А иногда заголовки просто описывают содержимое коммита:

  • More fixes for broken stuff
  • Sweet new API methods

Есть простое правило, которое позволит вам избегать ошибок.

Правильно составленный заголовок коммита должен завершать следующее предложение:

  • If applied, this commit will <заголовок коммита>

Например:

  • If applied, this commit will refactor subsystem X for readability
  • If applied, this commit will update getting started documentation
  • If applied, this commit will remove deprecated methods
  • If applied, this commit will release version 1.0.0

If applied, this commit will merge pull request #123 from user/branch

Убедитесь, что глаголы в других, не повелительных, наклонениях здесь не сработают:

  • If applied, this commit will fixed bug with Y
  • If applied, this commit will changing behavior of X
  • If applied, this commit will more fixes for broken stuff
  • If applied, this commit will sweet new API methods

Помните: использование повелительного наклонения важно только в заголовке коммита. В теле коммита это необязательно.


6. Переходите на следующую строку в теле на 72 символах


Сам Git не расставляет переносы строк автоматически. Редактируя тело комментария, вы должны помнить о правой границе и ставить переносы строк вручную.

Рекомендуется переходить на следующую строку на 72 символах, чтобы Git мог свободно расставлять отступы и всё еще влезать в сумме в 80 символов.

С этим может помочь хороший текстовый редактор. Довольно легко настроить, скажем, Vim, на перенос строки на 72 символах для написания сообщения к коммиту. Однако, так сложилось, что IDE ужасно плохо поддерживают умные переносы строк для сообщений к коммитам (хотя последние версии IntelliJ IDEA наконец стали лучше в этой части). (прим. пер. — возможно, на текущий момент все обстоит гораздо лучше).

7. В теле отвечайте на вопросы «что» и «почему», а не «как»


В этом коммите из репозитория Bitcoin дано отличное объяснение, что и почему изменилось:
commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.

   As exceptmask always included 'failbit', and setstate was always
   called with bits = failbit, all it did was immediately raise an
   exception. Get rid of those variables, and replace the setstate
   with direct exception throwing (which also removes some dead
   code).

   As a result, good() is never reached after a failure (there are
   only 2 calls, one of which is in tests), and can just be replaced
   by !eof().

   fail(), clear(n) and exceptions() are just never called. Delete
   them.

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

В большинстве случаев вы можете опустить подробности того, как именно были внесены изменения. Обычно, код говорит сам за себя в этом смысле (а если он настолько сложен, что требуются пояснения, то для этого есть комментарии в нем самом).

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

Может быть, в будущем вы поблагодарите сами себя за это!

Подсказки


Полюбите командную строку. Забудтье про IDE.


Есть множество причин — по количеству команд Git — использовать командную строку по максимуму. Git — безумно мощный инструмент; IDE — тоже, но каждая по-своему. Я ежедневно пользуюсь IntelliJ IDEA, часто имел дело и с другими (например, Eclipse), но никогда не видел, чтобы интеграция Git в IDE могла сравниться по простоте и возможностям с командной строкой (как только вы с ней разберетесь).

Определенные возможности IDE по контролю версий просто неоценимы, например автоматическое выполнение git rm, когда вы удаляете файл, или других нужных git-штук, когда вы его переименовываете. Но все гораздо хуже, когда вы пытаетесь с помощью IDE сделать коммит, слияние, перебазирование (rebase) или сложный анализ истории коммитов.

Когда требуется раскрыть полный потенциал Git, командной строке нет равных.
Помните, что используете ли вы Bash, Zsh или Powershell — существуют скрипты автодополнения команд, избавляющие вас от болезненной необходимости запоминать все подкоманды и опции.

Прочтите книгу Pro Git


Великолепная книга Pro Git (также на русском языке — прим. пер) есть в свободном доступе. Воспользуйтесь этим!
Поделиться публикацией

Похожие публикации

Комментарии 115
    –3
    • update
    • fix
    • code update
      0

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


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

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


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

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


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


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


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


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


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


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


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


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


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


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

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

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

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

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

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

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

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

              2. Ну и так, уже менее серьезно — можно сэкономить два символа на окончании «ed» и некоторых неправильных глаголах :)
                +1
                Коммит это именно что зафиксированная история, которую нельзя изменить. Можно сделать другой коммит зафиксировав другие изменения, переписав историю. Но от этого изначальный коммит не изменится.
                  –1
                  Я имею в виду, что git-коммит — это же не снапшот репозитория. Это скорей инструкция, как привести код к какому-то виду, и если применить эту инструкцию к кодовой базе — получится, например, исправление бага или добавление фичи.
                    +3
                    git-commit это как раз снапшот репозитория, а не инструкция к кодовой базе. git-commit не применяется, на него переключаются.
                      +1
                      Это в терминах меркуриала changeset — инструкция, что с кодом сделать, по сути патч.
                      В гите и терминология другая, и «переставлять местами, сливать, переносить» коммиты сложнее, и человеческих веток нету.
                    0
                    Мне кажется 2 и есть причина. Повелительное наклонение позволяет сэкономить пару символов, а все остальное уже backwards reasoning.
                    +5
                    Может это специфика именно en?

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

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


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


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

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

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

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


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

                            –1
                            Если у вас идет подряд с 10-к строк измененного текста, то как разбить на несколько логических коммитов?
                              +1

                              Непонятно, почему вопрос ко мне. Я такие ситуации просто не создаю.

                                –1
                                Посему утверждение
                                поддержка Git в IDEA очень хороша
                                очень некоректно.
                                В самой IDEA с git есть ряд мелких и неприятных багов и недороботок.
                                  0

                                  Все корректно.

                                +1
                                10-к строк измененного текста, то как разбить на несколько логических коммитов?

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

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


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


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


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

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

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

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

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

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

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

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

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

                                            Вот у нас во флоу есть такая задачка: перед вливанием таск-ветки в 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 :)

                                              0
                                              Интересные задачки о_О
                                                0

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


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

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


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

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

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

                                                    0

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


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

                                                      0

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

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

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


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

                                                      0
                                                      На сколько помню задача разбивания коммита в GUI реализована в SmartGit.
                                                      Все приведенные тут остальные использования git, где командная строка клеится через && некорректны.
                                                      С тем же успехом для такой операции можно написать скрипт и повесить его на кнопку (или вообще руками вызывать).
                                                      Вообще, использование GUI не обязывает отказываться от командной строки. Просто ускоряет и облегчает рутину.
                                                        0

                                                        Так и использование CLI не есть призыв отказаться от GUI :)

                                                          0
                                                          Ну как мне видится именно к этому и призывают.
                                                          Когда мне говорят что православно постоянно писать 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».

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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


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

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

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


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


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

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

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


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

                                                                      0
                                                                      Просто вставлю свои пять копеек, как пример «среднего» между совсем «бесполезными» и «идеальными» коммитами:
                                                                      [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» все-таки не опускаюсь (немного больше нуля все-таки из истории понятно).
                                                                        0

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


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

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


                                                                            Как автор:


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

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


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

                                                                              Жесть

                                                                      0

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

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

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


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


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


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

                                                                          0
                                                                          split файла на части гит не поймет, merge тоже. И переписывание прототипа на другой язык тоже не поймёт. Переезд с одной vcs на другую тоже это историю обнулить может.
                                                                          Поддержу предыдущего комментатора, если выбирать между нормальными комментариями в самом коде или в гите — предпочту первое.
                                                                          Некоторые настолько упарываются красотой истории коммитов, что это даже идет в ущерб качеству кода. По принципу: наткнулся на какую-то лажу, но не буду ее править прямо сейчас, потому что это затронет больше файлов, чем относится к текущему коммиту, ну а потом, конечно же, забуду про нее. Или разношерстное форматирование заединообразить не хотят, лишь бы блэймы не потерялись.
                                                                            0

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


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


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

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

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

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

                                                                          0
                                                                          Если для исправления бага понадобился некий неочевидный костыль — описать его рядом. Если же нет — какая разница, сколько там файлов было изменено?
                                                                          Комментарии в коде пишутся по другим принципам: они должны описывать, зачем тут эта фигня, и почему я не должен ее выкинуть :)
                                                                          Если в комментариях к коду вести историю проделанной работы — это жесть, лучше вообще не писать комментарии в таком случае.
                                                                          0
                                                                          Комменты к коду и комменты к коммитам совершенно разные вещи, и несут совершенно разные смысл. Коммит это изменение состояния проекта, и коммент описывает смысл этого изменения. А комменты к коду просто показывают что этот код делает
                                                                          +2
                                                                          Я против длинных простыней объяснений в коммитах.
                                                                          Наверняка есть Jira (или аналог), в котором описана задача, со скриншотами, коментариями и обсуждениями. Достаточно в начале каждого коммита писать номер задачи и краткую причину.
                                                                          • НЛО прилетело и опубликовало эту надпись здесь
                                                                              0
                                                                              В одном старом проекте перешли с TFS на GIT, и все коммиты стали пустым местом (реальный случай). И что?
                                                                                +2

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

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

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

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


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

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


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


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

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


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

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


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

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

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

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

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

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

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


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

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


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


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


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


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


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

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

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

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

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

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


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


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

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

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


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

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

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

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

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

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

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

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


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

                                                                                        0
                                                                                        Ладно автор из 2014-го года. Но в обсуждении перевода столько разных самостийных стилей написания комментариев к коммитам, и при этом ни одного упоминания Conventional Commits.
                                                                                          0
                                                                                          у себя придерживаюсь стиля распространенного во многих апачевских проектах, например 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. краткое описание, что сделано


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

                                                                                            Указываешь номер тикета и кратко что это, кому интересно — сам в трекере найдет все спеки и обсуждение.
                                                                                              0
                                                                                              Странно, но никто не упомянул, что данные правила частично совпадают со «стандартом» питона (PEP 8, PEP 257). Частично — в данных документах рекомендуется ставить точку в конце первой строчки Docstring.
                                                                                                0
                                                                                                В русском языке повелительное наклонение принимает форму заклинания, наговора, усиливающего вносимое изменение, — «Исправь то», «Сделай сё». А вместо точки в конце лучше ставить 'X', — «скрестить пальцы».

                                                                                                Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                                                                                                Самое читаемое