Автоматизированная генерации сообщений conventional commit

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

Как всё началось

Уже почти полгода я пользуюсь своей утилитой gh-commitmsg для генерации commit-сообщений, и она прочно вошла в мой повседневный workflow. Пожалуй, теперь это одна из самых часто используемых мной CLI-команд.

Идея создать такой инструмент пришла после знакомства с проектом gh-standup от Шона Годеке (Sean Goedecke – чувак живёт в Австралии, работает в ГитХабе и ведёт просто потрясающе информативный блог! Рекомендую к прочтению буквально каждый пост, это кладезь знаний о разработке). Это расширение для GitHub CLI, которое генерирует ежедневные отчёты о проделанной работе. Я подумал – а почему бы не применить тот же подход для автоматизации написания commit-сообщений? Так что код gh-standup я взял за основу, адаптировал под свои задачи, и получилась утилита, которой теперь пользуюсь постоянно.

Зачем это нужно

Основная мотивация была проста: хотелось, чтобы каждое commit-сообщение было информативным и хорошо оформленным, но при этом не тратить на это время. Когда пишешь вручную, легко что-то упустить или сформулировать не очень внятно. А когда LLM анализирует все изменения и генерирует сообщение в формате Conventional Commits – получается структурировано и полно. К тому же, это самое естественное применение возможностей LLM – анализировать код и саммаризировать информацию понятным языком.

Ещё один важный момент – мне хотелось, чтобы инструмент был бесплатным и не требовал настройки API-ключей от сторонних сервисов. Поэтому выбор пал на GitHub Models – бесплатный сервис от GitHub для работы с LLM. Достаточно быть аутентифицированным в GitHub CLI, и всё работает из коробки!

Технологический стэк

Выбор инструментов был вполне очевидным:

Go – язык для разработки расширений GitHub CLI. Компактный, быстрый, и идеально подходит для CLI-утилит.
GitHub CLI Extensions – механизм расширений позволяет легко интегрироваться с gh и использовать существующую аутентификацию.
GitHub Models API – бесплатный доступ к различным AI-моделям (по умолчанию используется gpt-4o-mini).
Just – удобная альтернатива Makefile для автоматизации сборки.
GitHub Actions – для CI/CD, автоматической сборки релизов под разные платформы.

Что получилось

Утилита работает очень просто: ты делаешь git add для изменений, которые хочешь закоммитить, а потом запускаешь gh commitmsg – и получаешь готовое сообщение в формате Conventional Commits!

Основные фичи

✅ Автоматическая генерация commit-сообщений из staged-изменений
✅ Формат Conventional Commits из коробки
✅ Поддержка любого языка через флаг --language (например, --language russian)
✅ Использование предыдущих коммитов как примеров для AI (по умолчанию 3, можно до 20)
✅ Выбор альтернативных моделей через --model (например, xai/grok-3-mini)
✅ Никаких API-ключей – работает через аутентификацию GitHub CLI
✅ Кросс-платформенность – собирается под Linux, macOS, Windows (тут скажу честно – проверял работу только на своей MacOS!)

Как это выглядит на практике

Типичный сценарий использования:

# Вносим изменения в код
git add .

# Генерируем commit-сообщение
gh commitmsg --language russian

# Получаем что-то вроде:
# feat: добавить поддержку конфигурационных файлов
#
# - Реализована загрузка настроек из .config.yml
# - Добавлена валидация конфигурации
# - Обновлена документация

Утилита анализирует не только сами изменения, но и историю предыдущих коммитов, чтобы генерировать сообщения в стиле, характерном для вашего проекта. Это реально помогает поддерживать единообразие! Даже такие мелочи, как ставите ли вы точку в конце строки, будут учтены LLM.

Личный опыт использования

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

Особенно ценю поддержку русского языка. Для личных проектов я предпочитаю коммитить на русском – так понятнее и естественнее. А для публичных репозиториев можно использовать английский, просто не указывая флаг --language.

Ещё один неожиданный бонус – LLM иногда замечает в изменениях то, что я сам упустил бы из виду. Например, если случайно добавил какой-то debug-код или временный комментарий, это может отразиться в сообщении коммита, и я сразу замечу, что нужно почистить код перед коммитом. Бывает также, что изменений слишком много и их стоит разбить на несколько небольших "тематических" коммитов. Это тоже будет видно из сгенерированного сообщения.

Ограничения

Не обошлось и без небольшой ложки дёгтя в виде ограничений GitHub Models.

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

По своему опыту заметил, что если изменения не влезают в контекст, то возможно коммит слишком большой и его стоит разбить на несколько. Также иногда перед генерацией стоит исключить из staging большие изменения в файлах вроде package-lock.json или uv.lock. Они не добавляют информативности, но зачастую легко могут съесть значительную часть контекста. Главное, не забыть добавить их в коммит после генерации описания.

Установка и использование

Установить утилиту проще простого:

gh extension install hazadus/gh-commitmsg

После этого можно сразу использовать:

# Базовое использование
gh commitmsg

# С указанием языка
gh commitmsg --language russian

# С выбором модели
gh commitmsg --model xai/grok-3-mini

# С использованием большего количества примеров из истории
gh commitmsg --examples 10

Обновление до новой версии:

gh extension upgrade commitmsg

Что дальше?

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

Если у вас есть идеи по улучшению – велкам в issues на GitHub! Или можете форкнуть проект и адаптировать под свои нужды – код доступен под лицензией MIT. Также надеюсь, что утилита вдохновит кого-то на создание своих инструментов, как меня вдохновил проект Шона Годеке!

Если вам понравилась идея описанного инструмента, посмотрите также мой проект gh-repomon. Там тот же стэк технологий используется для аналитики активности в репозиториях. Пока обкатываю эту утилиту, возможно позже расскажу о ней также подробно – если она покажет себя полезной.

Ссылки

Репозиторий gh-commitmsg на GitHub
gh-standup от Шона Годеке – источник вдохновения и основа для кода
Каталог GitHub CLI Extensions – нужно добавить к репо тэг gh-extensions, чтобы проект появился в этом каталоге
GitHub Models – бесплатный AI-сервис от GitHub
Conventional Commits – стандарт оформления commit-сообщений
GitHub CLI – официальная CLI-утилита для работы с GitHub