Git. Руководство по оформлению веток и коммитов10.06.2024 09:15

Git

Введение

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

Оформление ветки

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

Если вы любитель создавать названия по типу abcd, yourname, myawesomebranch, new-feature, test-1234 или, на худой конец, DEV-666, по номеру задачи в трекере, то спешу вас расстроить, все эти варианты далеки от идеала. По названию ветки должно быть понятно, что именно она делает, какая у нее основная функция. В этом нам поможет гибкая система типов и краткое именование поставленной задачи. Обо всем по порядку.

Формирование имени ветки

/--

В git можно создавать папки и подпапки. Достаточно добавить / в имени ветки и ваша ветка получит следующую структуру folder/name. Эта возможность помогает сортировать ветки в git. Правильность сортировки задает тип ветки, который ставится в начале ее названия:

• build: изменения, касающиеся процесса сборки (npm, vite);

• chore: изменения, не касающиеся кода напрямую, то что не увидит конечный пользователь (установка/удаление зависимостей, настройка проекта/инструментов);

• ci: изменения, касающиеся CI/CD;

• docs: изменения, касающиеся документации;

• feat: новая фича;

• fix: баг-фикс;

• perf: изменения, касающиеся улучшения производительности;

• refactor: изменения, не относящиеся ни к новой фиче, ни к фиксу бага;

• revert: отмена коммита;

• style: изменения, относящиеся к стилизации, форматированию;

• test: добавление недостающих тестов или корректирование уже существующих тестов.

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

После типа ветки идет /, затем через дефисы указывается либо бизнесс-группа (DEV, SUP и т.д.) и номер вашей задачи из трекера + короткое описание задачи, либо просто задается короткое описание задачи. Само описание задачи должно составлять не более 5–6 слов и вносить ясность в то, что именно делает данная ветка («add custom input», «fix issue with user avatar dimensions», «upgrade vite version» и т.д.)

Примеры правильного именования веток:

feat/DEV-666-add-custom-input

fix/DEV-1125-issue-with-user-avatar-dimensions

chore/DEV-25-upgrade-vite-version

style/add-outline-to-primary-button

Оформление коммита

Ветка создана. Код написан. Что дальше? Создается коммит — снепшот (от англ. snapshot — снимок) ваших наработок. Его сопровождает поясняющее сообщение, в котором описывается какая именно работа была проделана. Для того что бы быстро ориентироваться в общем потоке информации и сделать историю разработки как можно более прозрачной стоит уделить особое внимание составление сообщения.

Формирование сообщения коммита

: 

Для начала посмотрите на типы, которые мы с вами ввели для именования веток и проведите анализ кода, который хотите закоммитить. Каждый коммит должен содержать законченный, логически связанный код (исключением являются WIP-коммиты, об этом поговорим чуть позже). То есть если вы привыкли просто бездумно выполнять команду git add ., тем самым добавляя в коммит все что сделали в процессе работы, то сейчас самое время пересмотреть это действие.

Think about it. Meme

Логические куски кода легко поддаются сортировке и выбор типа коммита становится тривиальной задачей. Вы добавили новую функциональность — это тип feat. Исправили баг — это тип fix. Провели рефакторинг кода без изменения основной логики работы — это тип refactor. И т.д.

После добавления типа коммита вы ставите :, пробел и пишите короткое обобщенное название того, что именно сделали. Само сообщения должно писаться в повелительном наклонении, начинаться, как правило, с глагола («добавить», «убрать», «исправить», «изменить» и т.д) и не содержать какие-либо знаки препинания в конце.

feat: add booking widget to product page

refactor: remove info button in tariff card

ci: update CI/CD for performance reason

Если вы хотите развернуто описать проделанную работу, то создайте большое сообщение для коммита с заголовком, телом сообщения и подвалом (опционально). В этом вам поможет команда git commit, которая открывает встроенный в оболочку командной строки редактор кода (vim, nano и т.д.). Вы также можете воспользоваться GUI-вариантом в вашей IDE.

# HEADING 
feat: add button for loading new posts

# BODY
Add a button for loading new posts on blog page. It can be hidden if there're no more info and shown if it exists.

There is a small delay on button hidding(maybe it's a problem with rerendering), so it needs to be fixed on future refactoring.

# FOOTER(optional)
Signed-of-by: John Doe
Issue: DEV-123

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

P.P. S. Также хочу вам порекомендовать линтер CommitLint для проверки правильности оформления сообщений на основе заданных правил.

Git trailers

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

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

git config --global trailer..key ''

Примеры добавления алиасов для ключей трейлеров:

git config --global trailer.issue.key 'Issue'

git config --global trailer.sign.key 'Signed-of-by'

git config --global trailer.milestone.key 'Milestone'

Для того что бы добавить трейлер для вашего коммита достаточно использовать опцию --trailer 'keyAlias: ' при создании сообщения.

git commit -m 'feat: add new counter' --trailer 'issue: DEV-111'

git commit --trailer 'sign: John Doe'

Для последующего поиска коммитов по трейлерам можно воспользоваться несколькими командами:

git log --grep=": "

Данная команда ищет все совпадения в логе git’а по полному имени ключа и описанию трейлера.

Примеры:

git log --grep="Issue: DEV-111"

git log --grep="Signed-of-by: John Doe"

Или

git log --format="%h %(trailers:key=)" --grep="

git log --format="%h %(trailers:key=issue)" --grep="DEV-111"

git log --format="%h %(trailers:key=sign)" --grep="John Doe"

git commit -m 'WIP: '

git rebase -i 

reword f7f3f6d WIP: working on new product card UI
fixup 310154e WIP: update card styles
fixup a5f4a0d WIP: update card skeleton

# Rebase 710f0f8..a5f4a0d onto 710f0f8
#
# Commands:
# p, pick  = use commit
# r, reword  = use commit, but edit the commit message
# e, edit  = use commit, but stop for amending
# s, squash  = use commit, but meld into previous commit
# f, fixup  = like "squash", but discard this commit's log message
# x, exec  = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop  = remove commit
# l, label  = label current HEAD with a name
# t, reset  = reset HEAD to a label
# m, merge [-C  | -c ]  [# ]
# .       create a merge commit using the original merge commit's
# .       message (or the oneline, if no original merge commit was
# .       specified). Use -c  to reword the commit message.
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out