Commit-сообщения — это не просто формальность, это история вашего проекта, которую будут читать ваши коллеги по цеху, а возможно, и вы сами через полгода, год, когда забудете, зачем добавили эту непонятную строчку кода. В этой статье разберем, как делать понятную и читаемую историю комитов. Вы скажете себе спасибо.
Зачем заморачиваться с commit-сообщениями?
Представьте: вы ищете баг, который появился n-время назад, открываете историю комитов и видите:
* 3a7f2b1 fix bug
* 8d4e9c2 update
* 1b6f8a3 changes
* 9e2c4d7 asdf
* 5f1a8b9 работал над фичей
А теперь вгляните на этот пример:
* 3a7f2b1 fix: исправлена ошибка валидации email в форме регистрации
* 8d4e9c2 feat: добавлена возможность загрузки аватара пользователя
* 1b6f8a3 refactor: вынесена логика аутентификации в отдельный модуль
* 9e2c4d7 docs: обновлена документация API для работы с файлами
* 5f1a8b9 test: добавлены unit-тесты для корзины покупок
Видите разницу? Во втором примере сразу понятно, где именно и в чем были изменения кода. Этот подход профессионален.
Анатомия правильного commit
Базовая структура
<тип>: <описание>
<подробности (опционально)>
<футер с ссылками (опционально)>
Заголовок — самая важная часть:
- Короткий (до 50 символов)
- Понятный, не имея контекста
- Без точки в конце
- Начинается с маленькой буквы после двоеточия
Тело — для сложных изменений, когда нужны пояснения.
Футер — ссылки на задачи, breaking changes и прочая служебная и справочная информация.
Типы commitов с примерами
feat — новый функционал
- feat: добавлена возможность сортировки товаров по цене
- feat: реализована двухфакторная аутентификация
- feat: добавлен экспорт отчетов в Excel
fix — исправление багов
- fix: исправлена ошибка 404 на странице профиля
- fix: исправлена ошибка деления на ноль в калькуляторе
- fix: устранена утечка памяти при загрузке файлов
refactor — рефакторинг без изменения функциональности
- refactor: упрощена логика валидации форм
- refactor: вынесены константы в отдельный файл
- refactor: оптимизированы SQL-запросы
docs — изменения в документации
- docs: добавлено описание API для работы с заказами
- docs: обновлена схема базы данных
- docs: исправлены опечатки в README
style — форматирование, отступы
- style: исправлено форматирование в файле utils.js
- style: приведен код к стандарту ESLint
- style: добавлены пропущенные точки с запятой
test — тесты
- test: добавлены unit-тесты для модуля аутентификации
- test: добавлены интеграционные тесты
- test: исправлен падавший тест для API корзины
chore — обновления зависимостей, настройки
- chore: обновлены зависимости до последних версий
- chore: настроен ESLint для проекта
- chore: добавлен pre-commit hook
Что такое хорошо и что такое плохо
Плохие примеры
- fix bug // Какой баг? Где?
- update // Что обновили?
- changes // Какие изменения?
- работаю над фичей // Над какой? Что сделано?
- фикс // Что исправили?
- ааа наконец-то работает // Что работает?
- small changes // Конкретики ноль
- добавил новую фичу // Какую фичу, куда добавил?
Хорошие примеры
- fix: исправлена ошибка валидации email в форме регистрации
- feat: добавлена пагинация для списка товаров (50 элементов на страницу)
- refactor: вынесена логика расчета скидок в отдельный сервис
- docs: обновлена документация по развертыванию проекта
- test: добавлены интеграционные тесты для API корзины
- style: приведен код к единому стилю согласно Prettier
- chore: обновлен Webpack с версии 4 до 5
Conventional Commits — стандарт для команд
Если работаете в команде, используйте строгий формат Conventional Commits:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Scope — область изменений в скобках:
Примеры:
- feat(auth): добавлена поддержка OAuth2
- fix(database): исправлена ошибка подключения к MongoDB
- docs(api): обновлена документация для endpoints
Breaking changes(означают, что код, который работал с предыдущей версией вашего проекта, больше не будет работать правильно после применения этого коммита) помечаются восклицательным знаком:
- feat!: изменен формат API ответов с XML на JSON
- fix(auth)!: изменена структура JWT токенов
Правила написания
1. Правильная трактовка
- "добавлена функция поиска"
- А не:
- "добавляю функцию поиска"
- "добавил функцию поиска"
2. Больше конкретики конкретными
- fix: исправлена ошибка 500 при загрузке файлов больше 10MB
А не:
- fix: исправлена ошибка с файлами
3. Объясняйте "зачем", а не только "что"
Важно отвечать в комите не только на вопрос "что поменялось?", а еще и на вопрос "зачем эти изменения были внесены?"
- refactor: вынесена валидация в middleware
- Повторяющийся код валидации в каждом контроллере
- усложнял поддержку. Теперь вся логика в одном месте.
- Closes #156
Полезные инструменты
Commitizen — интерактивный помощник
- npm install -g commitizen
- npm install -g cz-conventional-changelog
Запускаете git cz вместо git commit, отвечаете на вопросы — получаете идеальный commit.
Commitlint — проверка сообщений
- npm install -D @commitlint/cli @commitlint/config-conventional
Автоматически проверяет, соответствуют ли ваши commit стандартам.
Шаблон для commitов
Создайте файл .gitmessage:
# <type>: <subject>
#
# <body>
#
# <footer>
И настройте Git:
- git config commit.template .gitmessage
Теперь каждый раз при git commit будет открываться шаблон и тебе нужно будет просто заполнить поля, не тратя время на воссоздания структуры.
Подробнее о каждом из них, можете почитать в интернете.
Как исправить неудачные комиты
Исправить последний commit
- git commit --amend -m "изменное правильное сообщение"
Объединить несколько мелких commitов
- git rebase -i HEAD~3 # последние 3 commit'а
- # В редакторе замените "pick" на "squash" для объединяемых
Интерактивный rebase для переписывания истории
- git rebase -i HEAD~5
- # Можете изменить, объединить или удалить комиты.
Главное не переписывайте историю, если код уже запушен в общий репозиторий!
Работе в команде
Важно перед началом работы обговорить, как вы будите писать commit messages. Это мелочь, но важно. Ваши комментарии к изменениям должны быть в едином стиле.
Задайте себе эти вопросы
- Писать на русском или английском?
- Какие типы commit'ов использовать?
- Нужен ли scope?
- Когда писать подробное описание?
Полезные привычки
Вот список полезных привычек, которые сделают ваши комиты лучше:
- Делайте атомарные commit'ы — один commit = одно логическое изменение
- Коммитьте чаще — лучше много маленьких, чем один огромный
- Используйте git add -p для частичного добавления изменений
- Перечитывайте сообщения перед отправкой
Если хотите серьезно погрузиться в IT, но программирование кажется сложным, есть отличная альтернатива с низким порогом входа. Курс "Профессия тестировщик" от SkillFactory научит находить баги в программах, работать с тест-кейсами и автоматизировать задачи. Это идеальный старт для новичков, а еще помогут с трудоустройством.
👉 Подробнее о курсе и скидках здесь.
Реклама. ООО Скилфэктори, ИНН 9702009530, erid: LdtCK5EkP
Вывод
Писать хорошие commit сообщения - это обязанность каждого программиста, это базовый и очень полезный навык, овладев которым вы будете себе крайне благодарны!
А больше интересного в моем телеграм канале!
Буду рад вашей поддержке в виде лайка и подписки. Всем добра!❤️