↓Перейти к содержанию
  1. Git: руководства и команды/

Лучшие практики написания сообщений коммитов: полное руководство

·5 минут·

Хорошо написанное сообщение коммита стоит больше, чем его кажущаяся тривиальность. Через шесть месяцев, когда вы будете искать «а почему же мы изменили этот код», git log с правильными сообщениями даст ответ за секунды. С git commit -m "исправления" — вы потратите часы на git blame и чтение кода.

Почему качественные сообщения коммитов важны #

Посмотрите на два варианта истории:

Плохая история:

fix
update
changes
asdf
work in progress
исправил
добавил

Хорошая история:

feat: добавлена OAuth2 авторизация через Google
fix: исправлена ошибка валидации email в форме регистрации
refactor: упрощена логика расчёта скидок
docs: добавлена документация по API авторизации
test: добавлены тесты для модуля корзины

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

Плохие коммиты приводят к тому, что git bisect превращается в мучение, Code Review теряет контекст, новые разработчики не могут понять эволюцию кода.

Структура идеального сообщения коммита #

Общепринятая структура (основана на тексте Тима Поупа):

<краткое описание> (до 50 символов)
<пустая строка>
<подробное объяснение> (каждая строка до 72 символов)
<пустая строка>
<ссылки на задачи>

Первая строка (subject): краткое описание что было сделано. До 50 символов. Используйте повелительное наклонение: «Добавить», «Исправить», «Удалить» (не «Добавлено», «Исправил»). Не ставьте точку в конце.

Пустая строка: обязательный разделитель между заголовком и телом. git log --oneline показывает только заголовок, git show — полное сообщение.

Тело сообщения: объясняйте ЧТО и ПОЧЕМУ, не КАК (КАК видно из кода). Оберните строки на 72 символах. Используйте маркированные списки для перечислений.

Ссылки на задачи: Fixes #123, Refs #456, Closes #789.

Типы коммитов: Conventional Commits #

Conventional Commits — открытый стандарт для структурированных сообщений коммитов. Используется в крупных проектах (Vue.js, Angular, многих других).

Структура:

<тип>[область]: <описание>

[тело]

[ссылки]

Основные типы:

feat — новая функция для пользователя:

git commit -m "feat: добавлена возможность экспорта в CSV"
git commit -m "feat(auth): добавлена двухфакторная аутентификация"

fix — исправление ошибки:

git commit -m "fix: исправлен расчёт суммы в корзине при скидках"
git commit -m "fix(api): исправлен статус 500 при пустом запросе"

docs — изменения документации:

git commit -m "docs: обновлён README с инструкциями по установке"
git commit -m "docs(api): добавлена документация по эндпоинту /users"

style — форматирование, нет изменений функционала:

git commit -m "style: исправлены отступы в компоненте Header"

refactor — рефакторинг без изменения функционала:

git commit -m "refactor: упрощена логика парсинга конфигурации"

perf — улучшения производительности:

git commit -m "perf: добавлено кэширование запросов к БД"

test — добавление или обновление тестов:

git commit -m "test: добавлены unit-тесты для модуля авторизации"

chore — обновление зависимостей, конфигурации:

git commit -m "chore: обновлены зависимости до последних версий"
git commit -m "chore: добавлен .editorconfig"

ci — изменения конфигурации CI/CD:

git commit -m "ci: добавлен запуск тестов в GitHub Actions"

BREAKING CHANGE — обозначение несовместимого изменения API:

git commit -m "feat!: изменён формат ответа API /users

BREAKING CHANGE: поле 'name' переименовано в 'full_name'"

Практические примеры хороших сообщений #

Простой commit:

git commit -m "fix: исправлена ошибка валидации email в форме входа"

Подробный commit:

git commit -m "fix: исправлена ошибка валидации email в форме регистрации

Была проблема с регулярным выражением — оно не принимало
email-адреса с двойными символами перед @, например [email protected].

Теперь используется встроенная валидация HTML5 вместо
самописного regex.

Fixes #456"

Коммит с новой функцией:

git commit -m "feat: добавлена двухфакторная аутентификация

- Интеграция с Google Authenticator (TOTP)
- QR-код для быстрой настройки приложения
- Резервные коды для восстановления доступа
- Принудительное включение для администраторов

Closes #123
Refs #456"

Что не писать в сообщениях коммитов #

Плохо — неинформативно:

git commit -m "fixed stuff"
git commit -m "changes"
git commit -m "update"
git commit -m "."
git commit -m "asdf"

Плохо — описывает КАК, а не ЧТО/ПОЧЕМУ:

git commit -m "изменил переменную i на j в файле utils.js строка 42"

Плохо — слишком длинный заголовок:

git commit -m "Добавил новую функцию авторизации через Google OAuth2 с поддержкой обновления токенов и двухфакторной аутентификации"

Инструменты для автоматизации #

commitizen — интерактивный инструмент для создания правильных коммитов:

npm install -g commitizen
cz init
git cz  # вместо git commit — откроется интерфейс выбора типа

commitlint — проверка сообщений коммитов:

npm install -D @commitlint/cli @commitlint/config-conventional

# .commitlintrc.js
module.exports = { extends: ['@commitlint/config-conventional'] }

husky — Git hooks для автоматической проверки:

npm install -D husky
npx husky add .husky/commit-msg 'npx --no commitlint --edit "$1"'

conventional-changelog — автогенерация CHANGELOG из коммитов:

npm install -g conventional-changelog-cli
conventional-changelog -p angular -i CHANGELOG.md -s

Шаблон сообщения коммита #

Настройте шаблон коммита для вашего редактора:

# Создать шаблон
cat > ~/.gitmessage << 'EOF'
# <тип>[область]: <описание> (до 50 символов)
# |<-- 50 символов -->|
feat:

# Объясните ПОЧЕМУ это изменение необходимо (до 72 символов):
# |<-- 72 символа -->|


# Ссылки на задачи:
# Fixes #
# Refs #
# BREAKING CHANGE:
EOF

# Установить как шаблон
git config --global commit.template ~/.gitmessage

Часто задаваемые вопросы #

Что такое тело сообщения и нужно ли его всегда писать? Тело — это текст после пустой строки. Нужно для сложных изменений, где важен контекст. Для простых fix/style — достаточно одной строки заголовка.

Какой максимальный размер для заголовка коммита? Рекомендуется до 50 символов. GitHub обрезает заголовок в интерфейсе, если он длиннее 72 символов. Жёсткого ограничения нет, но правило 50 символов — хорошая практика.

Нужно ли использовать Conventional Commits для небольших проектов? Conventional Commits особенно полезны при автоматической генерации changelog и семантическом версионировании. Для личных проектов достаточно просто информативных заголовков.

Можно ли редактировать сообщение коммита после создания? Последний коммит: git commit --amend. Более ранние коммиты: git rebase -i HEAD~N. Но если коммит уже запушен — изменение перепишет историю, что проблематично для командных веток.

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

Заключение #

Хорошие сообщения коммитов — это инвестиция в будущее. Пять секунд на написание правильного сообщения могут сэкономить часы отладки через полгода. Начните с простого: придерживайтесь структуры <тип>: <описание> и объясняйте ПОЧЕМУ в теле сообщения.

Следующий шаг — читайте полное руководство по git commit для изучения всех параметров команды. Для изучения истории коммитов читайте руководство по git log.