Как написать эффективное и полезное сообщение Git Commit

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

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

Структура хорошего сообщения фиксации

Хороший пример сообщения фиксации включает четыре раздела: Тип, Описание, Тело и Нижний колонтитул.

Вот так:

: 
[необязательное тело]
[необязательный нижний колонтитул]

Тип

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

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

Описание

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

При написании описания помните следующее:

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

Например:

feat: Реализовать переключатель темного режима для домашней страницы

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

Тело (необязательно)

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

Вот несколько моментов, на которые стоит обратить внимание при написании основной части сообщения о коммите:

• Git никогда не переносит текст автоматически, поэтому вручную переносите его на 72 символа, когда вы пишете тело. Это дает Git достаточно места для отступа текста, делая его более читабельным.
• Используйте тело, чтобы объяснить, что произошло при изменении, почему вы внесли изменение и причины, лежащие в основе вашего изменения.
• Вам нужно оставить пустую строку между строкой описания и телом. Это позволяет Git различать их.
• Если фиксация вводит несколько изменений или затрагивает разные области кодовой базы, рассмотрите возможность использования маркеров или абзацев для разбивки изменений. Это улучшает читабельность и помогает читателям понять различные аспекты коммита.

Например:

feat: добавить GitHub в качестве провайдера OAuth
Интегрируйте GitHub в качестве поставщика OAuth, чтобы обеспечить бесперебойную работу 
аутентификация с помощью учетных записей GitHub.
- Реализовать поток аутентификации OAuth с помощью GitHub API.
- Настройте необходимые конечные точки и параметры для аутентификации GitHub.
- Обновлен пользовательский интерфейс, чтобы включить возможность входа в GitHub.

В приведенном выше примере показано хорошее сообщение фиксации Git для функции, которая добавляет GitHub как провайдер OAuth к вашему приложению. Это сообщение фиксации содержит краткую сводную строку (не более 50 символов), более подробный пояснительный текст (примерно до 72 символов) и маркеры для дополнительной информации.

Раздел нижнего колонтитула в сообщении фиксации — это необязательная часть, которая предоставляет дополнительную информацию или метаданные, связанные с фиксацией. Обычно он помещается после раздела body, отделяемого пустой строкой. Нижний колонтитул может содержать различные типы информации, такие как ссылки на связанные проблемы, теги или специальные примечания.

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

Например:

feat: добавить GitHub в качестве провайдера OAuth
Интегрируйте GitHub в качестве поставщика OAuth, чтобы обеспечить бесперебойную работу 
аутентификация с помощью учетных записей GitHub.
- Реализовать поток аутентификации OAuth с помощью GitHub API.
- Настройте необходимые конечные точки и параметры для аутентификации GitHub.
- Обновлен пользовательский интерфейс, чтобы включить возможность входа в GitHub.
Решает: #123
См. также: № 456, № 789.

Нижний колонтитул ссылается на связанную проблему № 123 и упоминает другие связанные проблемы № 456 и № 789 для дополнительного контекста.

Добавление сообщения фиксации

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

-м flag идеально подходит для коротких сообщений фиксации, обычно включающих тип и описание.

Например:

git commit -m "рутинная работа: сменить линтер на ESlint"

Однако, если ваше сообщение о коммите требует более подробной информации, например тела и нижнего колонтитула, вам лучше написать коммит в текстовом редакторе или IDE.

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

Например:

git commit --file commit_message.txt

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

Вы также можете указать git открыть редактор по умолчанию, чтобы написать более длинное сообщение. Если у вас установлена ​​переменная среды GIT_EDITOR или EDITOR, git откроет эту программу, когда вы запустите голый git совершить команда.

Почему вы должны писать хорошие сообщения о коммитах

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

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