Git it up!

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

Использованные источники: https://habr.com/post/183646/ https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit# https://habr.com/post/174467/#typicalscenario

Итак, приступим!

Стиль написания коммитов

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

Зачем это вообще нужно? Чтобы экономить время и нервы, не больше и не меньше. Это мы еще обсудим чуть позже, а пока рассмотрим как же вообще именуются коммиты.

Общий стиль

Если пройтись по тем же коммитам с GitHub, то можно увидеть довольно обширное количество вариантов написания коммитов. Основные рекомендации по написанию можно выделить такие:

Что сделать + для какой сущности + подробности (необязательно)

Большие сообщения в коммите

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

У команды, а ещё лучше — у организации, должен существовать единый подход к написанию коммитов, который должен определить три аспекта:

• Стиль. Синтаксис разметки, поля переноса, грамматика, заглавные буквы, пунктуация и проч. В итоге вы получите журнал логов, который не только приятно читать, но и который реально будет постоянно читаться.
• Контент. Какую информацию должен содержать текст сообщения коммита? Есть ли он вообще? Что в нем не должно содержаться?
• Метаданные. Как нужно ссылаться на идентификаторы issues, номера пул-реквестов и т. д.?

Существуют общепринятые соглашения о сообщениях Git.

Семь правил отличного комментария к коммиту

1. Отделяй тему от тела пустой строкой. Текст до первой пустой строки в сообщении фиксации рассматривается как заголовок коммита, и этот заголовок используется во всем Git. Иногда хватает и одной строки, особенно когда изменение настолько простое, что не требуется никакого дополнительного контекста. В Git есть другие места, в которых учитываются заголовок и тело коммита, но ничто не работает как нужно без пустой строки между ними
2. Ограничь строку темы 50 символами. «Краткость — сестра таланта.»
3. Начинай строку темы с заглавной буквы
4. Не завершай строку темы точкой. И вообще Убираем лишние знаки препинания Это общеепринятое редакторское правило для оформления заголовков
5. Используй императив в строке темы. Повелительное наклонение означает «устное или письменное распоряжение, команда или инструкция». Когда пишешь свои сообщения коммитов в императиве — следуешь встроенным соглашениям Git. Повелительное наклонение кажется грубым, поэтому мы не часто используем его. Но оно отлично подходит для написания тем коммитов. Одна из причин этого то, что сам Git использует его всякий раз, когда создает коммит от вашего имени.
6. Ограничь тело 72 символами в ширину. Когда коммит заслуживает немночто-то подобноего объяснения и контекста, нужно написать тело. азделение темы и тела окупается при просмотре лога. Git никогда не делает автоматического обтекания текстом. Когда пишешь тело коммита, нужно помнить о его правой границе и переносить текст вручную. Рекомендация говорит о том, что это нужно делать на 72 символах. Так Git будет иметь достаточно места для отступов текста и сохранит ширину в 80 символов.
7. Используй тело, чтобы объяснить, “что” и “почему”, а не “как”
8. Русский язык. Нет ничего постыдного в том, чтобы использовать русский язык в коммитах. Но делать это нужно только в том случае, если вы на 1000% уверены, что данный код будет интересен только русскоязычным людям.

# Вывести полную информацию о коммитах
$ git log

# Вывести только заголовки коммитов
$ git log --oneline

# Вывести заголовки коммитов с группировкой по пользователям
$ git log shortlog

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

Этот коммит позволяет:

• Исправить стиль комментариев
• Добавить стилевое правило для текстового выделения
• Исправить поведение функции function()
• Изменить что-то

Указываем тип коммита

Есть несколько заранее определенных типов:

• feature — используется при добавлении новой функциональности уровня приложения
• fix — если исправили какую-то серьезную багу
• docs — всё, что касается документации
• style — исправляем опечатки, исправляем форматирование
• refactor — рефакторинг кода приложения
• test — всё, что связано с тестированием

Указываем область действия (scope)

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

Например, может быть область видимости модуля: Или область видимости файла:

Для чего всё это

Как я уже говорил в самом начале статьи, для сохранения времени и нервов! Путём упрощения следующих операций:

• Автоматическая генерация списка изменений (CHANGELOG.md и подобные). Даже если он не сформируется полностью, то будет хотя бы какя-то отправная точка для внесения небольших поправок.
• Игнорирование неподходящих коммитов при поиске места, где все сломалось (например, с помощью git bisect).Коммиты, улучшающие документацию, тесты, стиль кода и т.д. могут сразу быть пропущены.
• Просто более насыщенная и понятная история развития проекта.

Примеры