Как правильно составлять описания коммитов и почему это важно
2026-02-26 18:33 Diff
https://ru.hexlet.io/blog/posts/git-commit-message

Примечание — Это адаптированный перевод статьи Криса Бимса How to write a Git commit message. Повествование ведётся от имени автора оригинала.

Содержание

История

Заглянув в историю изменений (коммитов) какого-то рандомного Git-репозитория, вы наверняка заметите, что описания коммитов (commit messages) написаны в той или иной степени беспорядочно. Например, посмотрите на описания коммитов, которые я написал, когда начинал контрибьютить в Spring:

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

Какие из этих описаний вы прочитаете охотнее? Старые отличаются по форме и по длине, а новые более лаконичные и однообразные. Старые как будто написаны хаотично и без системы, а новые явно писались осознанно и по упорядоченным правилам.

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

Контрибьюторы этих репозиториев понимают, что правильно оформленные описания — лучший способ передать контекст коммита другим контрибьюторам, а также будущему себе. Диф помогает понять, что именно меняет коммит. Но только описания коммитов помогут понять, зачем это меняется. Важность этого момента хорошо объясняет разработчик Петер Хуттерер (Peter Hutterer) в своём посте. Вот ключевая цитата из него:

Тратить время на восстановление контекста создания кода слишком дорого. Нельзя полностью обойтись без этого, но мы должны минимизировать такие затраты ресурсов. Правильные описания коммитов уменьшают необходимость восстанавливать контекст. В конце концов по описаниям коммитов можно понять, насколько хорошо программист работает в команде.

Если вы не задумывались, зачем нужны правильные описания коммитов, то наверняка вы не очень часто пользовались командой git log. Фактически, это порочный круг: из-за беспорядка в истории коммитов разработчики не хотят заглядывать в неё или заботиться о корректности собственных описаний коммитов. А история остаётся беспорядочной и неудобной, потому что разработчики не пользуются ей и не заботятся о корректности описаний коммитов.

Но правильно оформленная история коммитов — полезная и удобная вещь. Здесь вам пригодятся комманды git blame, revert, rebase, log, shortlog и так далее. С правильно оформленной историей изменений просмотр коммитов других разработчиков приобретает смысл. Кстати, при правильном оформлении истории изменений разобраться в ней можно самостоятельно, не привлекая к этой задаче авторов других коммитов. Вы получаете возможность понять, почему были внесены те или иные изменения в код несколько месяцев или лет назад.

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

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

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

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

Стиль

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

Контент

Что нужно писать в описании коммита? Чего в нём быть не должно?

Метаданные

Как нужно отмечать ID issue, номера пулреквестов и так далее?

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

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

Правило 1: оставляйте пустую строку между заголовком и описанием

Отрывок из справочных материалов о git commit:

Хоть это и не обязательное требование, рекомендуется начинать описание коммита со строки длиной до 50 символов, которая обобщает изменения. За ней должна следовать пустая строка, а затем более подробное описание коммита. Текст до пустой строки — это заголовок описания коммита, он может использоваться в разных командах Git. Например, Git-format-patch(1) превращает коммит в электронное письмо, в теме которого используется заголовок описания, а в теле — само описание.

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

В данном случае дополнительная информация не нужна. Если кому-то захочется узнать, какие именно ошибки были исправлены, это можно сделать с помощью комманд git show, git diff или git log -p.

Если вы делаете подобный коммит, удобно воспользоваться опцией -m в git commit:

А если коммит требует дополнительного объяснения, которое поможет другим разработчикам получить контекст, нужно делать подробное описание.

Подробные описания коммитов с заголовком и телом неудобно писать с помощью опции -m в командной строке. В этом случае лучше делать описание коммита в редакторе. Если вы ещё не настроили редактор для работы с Git, прочитайте этот раздел документации, а также обратите внимание на наш курс «Настройка окружения».

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

А теперь выведем только заголовок с помощью git log --oneline:

Или с помощью команды git shortlog выведем сгруппированные по авторам коммиты. Здесь снова выводится только заголовок описания:

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

Правило 2: ограничивайте длину заголовка 50 символами

Это не жёсткое ограничение, а практически полезная рекомендация. Соблюдение этого правила гарантирует читабельность заголовка. Также она заставляет автора коммита задуматься и описать изменения максимально коротко.

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

Пользовательский интерфейс GitHub учитывает эти соглашения. Он предупреждает вас, если длина заголовка превышает 50 символов. А если заголовок превышает 72 символа, он обрезается. Поэтому старайтесь уложиться в 50 символов, а 72 символа считайте красной чертой.

Правило 3: пишите заголовок с прописной (заглавной) буквы

Это очень простое правило: всегда пишите заголовок описания с прописной буквы. Правильный пример:

Неправильный пример:

Правило 4: не ставьте точку в конце заголовка описания

Это ещё одно простое правило: в конце заголовка точка не ставится. Кстати, лишние знаки пунктуации могут помешать вам уложиться в лимит длины 50 символов, о котором шла речь выше. Правильный пример:

Неправильный пример:

Правило 5: используйте повелительное наклонение в заголовке

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

  • Сделай уборку
  • Закрой дверь
  • Вынеси мусор

Все семь правил из этой статьи сформулированы в повелительном наклонении. Например, «не ставьте точку в конце заголовка», «пишите заголовок с прописной буквы».

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

А вот сообщение, которое создаётся при использовании команды git revert:

Ещё один пример — сообщение, которое создаётся, когда вы нажимаете кнопку Merge, чтобы принять пулреквест:

Поэтому использование повелительного наклонения соответствует общепринятым соглашениям 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 символов.

Правило 7: в теле описания отвечайте на вопросы «что?» и «почему?», а не «как?»

Пример описания ниже отлично показывает, как правильно объяснять, что и почему изменилось.

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

Обычно можно не писать, как именно сделаны изменения. Если код настолько сложный, что требует дополнительных пояснений, их можно сделать в комментариях. Сфокусируйтесь на объяснении причин изменений — на том, как всё работало до изменений и что здесь было не так, и на том, как оно работает сейчас.

В будущем другие мейнтенеры поблагодарят вас за это, и, возможно, одним из них будете вы!

Вместо заключения: полезные советы

Полюбите командную строку, используйте её вместо IDE

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

Помните об автодополнении, такая функция есть и в Bash, и в Zsh, и в Powershell. Автодополнение избавляет вас от необходимости запоминать полные команды.

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

Её можно бесплатно скачать по ссылке.