Как назвать первый коммит

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

the Octobi Wan Catnobi

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

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

Общий стиль

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

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

Старайтесь найти единый стиль для коммитов и придерживаться его. Для себя я нашел удобным такой стиль, когда я сначала указываю что я делаю. Например, add . После этого я указываю что-то, над чем я произвожу действие. Например, ui-bootstrap.js dependency . В большинстве случаев такой записи более чем достаточно. Если есть еще какая-то пояснительная надпись, то ее лучше вынести в отдельную большую запись, о чем мы еще поговорим. Если запись маленькая, но очень нужная, то можно дописать её прямо к коммиту. Но лучше еще раз задуматься, действительно ли нужна эта надпись, или она будет привлекать ненужное внимание.

dependency for managing ui-bootstrap.js components was added here on 18.06.2013 by olegafx

add ui-bootstrap.js dependency

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

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

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

replace twitter-bootstrap.css with pure.css Made UI much cleaner. BREAKING CHANGE. You need to use new class-names for grid-related elements.

Пишем сообщение с маленькой буквы

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

Add ui-bootstrap.js dependency ADD ui-bootstrap.js dependency

add ui-bootstrap.js dependency

НЕ используем прошедшее время

Чем проще, тем лучше. Прошедшее время слишком усложняет чтение сообщений. Предстаьте, что вы обращаетесь к Git: «Git, добавь», «Git, удали» и т.д.

added ui-bootstrap.js dependency

add ui-bootstrap.js dependency

Убираем лишние знаки препинания

Например, зачем вам точка в конце сообщения? Итак понятно, что оно закончено. То же самое относится к точке с запятой.

add ui-bootstrap.js dependency;

add ui-bootstrap.js dependency

Русский язык

Нет ничего постыдного в том, чтобы использовать русский язык в коммитах. Но делать это нужно только в том случае, если вы на 1000% уверены, что данный код будет интересен только русскоязычным людям. Например, у вас есть скрипт для VK, который указывает на карте всех фанатов Стаса Михайлова. Очевидно, что это будет мало кому интересно среди зарубежных граждан. Да и для россиян тоже, если честно.

Причесываем коммиты перед отправкой

Все коммиты в локальном репозитории можно именовать как угодно. Если вам проще запомнить, что «temp commit 1» — это первая рабочая версия какой-то функциональности, а «temp commit 2» — это ее исправленная и отрефакторенная версия, то пожалуйста, никто особо вас ругать не будет. Но. Огроменное НО. Перед отправкой приведите, пожалуйста, свои коммиты в самый лучший вид. Для большинства случаев подойдет замечательная команда:

git rebase -i

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

Находим свой любимый стиль

Я нашел такой в проекте AngularJS. У них есть даже отдельный документ, посвященный оформлению коммитов. Все моменты, о которых я рассказал выше, есть в этом документе. И это прекрасно. Потому что мне приходилось искать эти моменты самому из разных источников, своего опыта, а здесь все лежит уже в одном месте и написано хорошим простым языком. Кратко рассмотрим основные моменты.

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

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

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

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

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

refactor(audio-controls) use common library for all controls

Или область видимости файла:

chore(Gruntfile.js) add watch task

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

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

Заключение

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

На этом всё. Если у вас есть интересные примеры именования из своих проектов, буду рад увидеть их в комментариях. Все ошибки в тексте можете присылать в личные сообщения.

Общепринятые Коммиты 1.0.0-beta.2

Как разработчики приложений с открытым исходным кодом, использующие слияние (squash) git’а в ветку master должны писать общепринятые сообщения коммитов.

Сообщения коммитов должны иметь следующую структуру:

[optional область]: [optional тело] [optional подвал]

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

fix: — коммит типа fix , который исправляет баги в вашем коде (он соотносится с PATCH в правилах семантического управления версиями).
feat: — коммит type feat , который добавляет новую функциональность в ваш код (он соотносится с MINOR в правилах семантического управления версиями).
BREAKING CHANGE: — коммит, который содержит текст BREAKING CHANGE: в начале своего необязательного тела или подвала, и несет в себе описание нарушений обратной совместимости в API (он соотносится с MAJOR в правилах семантического управления версиями). BREAKING CHANGE может быть частью коммита любого типа.
Другие: коммиты, отличные от fix: и feat: так же разрешены, например, commitlint-config-conventional (основанный на the Angular convention) рекомендует chore: , docs: , style: , refactor: , perf: , test: и другие. Мы так же рекомендуем improvement для коммитов, которые улучшают текущую реализацию без добавления новой функциональности или исправления ошибок. Обратите внимание, что данный тип коммитов не управляется данной спецификацией и не имеет никакого соотношения в правилах семантического управления версиями (за исключением случае, если он не содержит в себе BREAKING CHANGE). Область (scope) может быть определена для любого типа коммита, чтоб описать контекст коммита. Она содержится в круглых скобках, например, feat(parser): add ability to parse arrays .

Примеры

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

feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Коммит без тела

docs: correct spelling of CHANGELOG

Коммит с указанной областью (scope)

feat(lang): added polish language

Коммит, исправляющий баги и содержащий (необязательный) номер в баг-трекере (issue) в подвале

fix: minor typos in code see the issue for details on the typos fixed fixes issue #12

Вступление

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

Любой, кто обновился до новой версии патча зависимостей, только для того, чтобы увидеть, как его приложение начинает вываливаться с 500 ошибкой, знает, насколько важна хорошая читаемая история изменений приложения (и в идеале хорошо сохранившийся CHANGELOG).

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

Внедряя это соглашение, мы создаем общий язык, который упрощает отладку между проектами.

Спецификация

Слова “ДОЛЖЕН”, “ДОЛЖНО”, “ДОЛЖНЫ” (“MUST”, “SHOULD”, “SHALL”), “МОГУТ”, “МОЖЕТ” (“MAY”) и “НЕ ОБЯЗАТЕЛЬНАЯ” (“OPTIONAL”) в этом документе должны интерпретироваться как описано в RFC 2119.

Коммиты ДОЛЖНЫ начинаться с префикса, который содержит существительное feat , fix и др., за которым следует двоеточие и пробел.
Тип feat ДОЛЖЕН использоваться для коммитов, которые добавляют новую функциональность в ваше приложение или библиотеку.
Тип fix ДОЛЖЕН использоваться для коммитов, которые исправляют баги в вашем приложении или библиотеки.
НЕ ОБЯЗАТЕЛЬНАЯ область (scope) МОЖЕТ быть указана после типа. Область — это фраза, описывающая контекст кодовой базы, измененной коммитом, заключенная в круглые скобки. Например, fix(parser): .
Краткое описания ДОЛЖНО следовать сразу же после указания префикса типа/области. Краткое описание — это сжатое описание изменения кода, которое несет в себе коммит, например, fix: array parsing issue when multiple spaces were contained in string.
Тело коммита содержит в себе дополнительное, полное описание о изменении кодовой базы. Оно МОЖЕТ следовать после краткого описания. Тело ДОЛЖНО идти после краткого описания, через одну пустую строку.
Подвал МОЖЕТ идти после тела коммита через одну пустую строку. Подвал ДОЛЖЕН содержать дополнительную ссылку на запись в баг-трекере (issue) об изменениях в кодовой базы (т.е. issue, которое он исправляет, например Fixes #13 ).
Нарушения обратной совместимости ДОЛЖНЫ содержаться в самом начале тела или подвала коммита. Нарушения обратной совместимости ДОЛЖНЫ начинаться с текста в верхнем регистре BREAKING CHANGE , за которым следует двоеточие и пробел.
Описание нарушения обратной совместимости ДОЛЖНО следовать сразу же после BREAKING CHANGE: . Оно должно разъяснять, что изменилось в API. Например, BREAKING CHANGE: environment variables now take precedence over config files.
Подвал ДОЛЖЕН содержать только BREAKING CHANGE , внешние ссылки, ссылки на номера задач в баг-трекере (issue), и другую мета-информацию.
Типы отличные от feat и fix МОГУТ использоваться в сообщениях коммитов.

Почему нужно использовать Общепринятые Коммиты

Автоматически создаваемые CHANGELOG’и.
Автоматически определяемая семантическая версия приложения или библиотеки (основываясь на типах коммитов).
Коммуникация о характере изменения между товарищами по команде, общественностью и другими заинтересованными сторонами.
Автоматически срабатываемый процесс сборки и публикации.
Людям проще участвовать в вашем проекте, потому что им доступна более структурированная история коммитов.

FAQ

Как я должен писать сообщения коммитов на начальной стадии разработки?

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

В каком регистре я должен писать заголовки коммитов?

Любой регистр можно использовать, но лучше во всей истории использовать один стиль.

Что мне делать, если коммит должен содержать больше одного типа?

Вернитесь назад и сделайте несколько коммитов, если это возможно. Часть из преимуществ использования Общепринятых Коммитов

это его способность побуждать делать более организованные коммиты и PR’ы.

Разве это не препятствует быстрому развитию и быстрой интеграции?

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

Могут ли Общепринятые Коммиты заставить разработчиков ограничивать их типы коммитов, потому что им придется думать об этих типах?

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

Как она связывается с правилами семантического управления версиями SemVer?

fix тип коммита должен быть отражен в PATCH -релизе. feat тип коммита должен быть отражен в MINOR -релизе. Коммиты с BREAKING CHANGE в теле или подвале, не зависимо от типа, должны быть отражены в MAJOR -релизе.

Как я должен версионировать мои расширения к спецификации Общепринятых Коммитов, например, @jameswomack/conventional-commit-spec ?

Мы рекомендуем использовать SemVer для релизов ваших расширений к этой спецификации (и рекомендуем делать эти расширения!).

Что мне делать, если я случайно использовал не тот тип коммита?

Что если вы использовали тип, который имеет спецификацию, но это неправильный тип. Например, fix вместо feat

Перед слиянием или релизом ошибки, мы рекомендуем использовать git rebase -i для редактирования истории коммитов. После release , исправления будут отличаться в зависимости от того, какие инструменты вы используете.

Когда вы использовали тип, не описанный спецификацией, например, feet вместо feat

Это не конец света, это просто обозначает, что коммит будет упущен при работе утилит, основанных на спецификации.

Должны ли все мои соавторы использовать спецификацию Conventional Commit?

Нет! Если ваш рабочий процесс основа на использовании слияния (squash) Git, сопровождающий проекта может отчистить историю всех предыдущих коммитов при их слияния, не добавляя рабочей нагрузки на случайные коммиты. Обычно, рабочий процесс строится на том, что ваша система Git автоматически объединяет (squash) все предыдущие коммиты пред перед pull-запросом и предоставляет форму сопровождающему проекта для ввода нового коммита.

bibendi / gist:7941823

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

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

Можно указывать несколько типов через запятую.

Здесь следует написать затронутые части (например, lynx или tool_chain )

Лучше написать грамотно по-русски, чем неграмотно по-английски!

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

На английском:

fix NoMethodError in RemoteReader

Первое слово — глагол в неопределнной форме.

На русском:

исправление ошибки NoMethodError в RemoteReader'е

Первое слово — отглагольное существительное.

Не нужно писать в сообщении номер таска из Джиры или тикета с Гитхаба — для этого есть тело коммита (см. далее).

fix(lynx): fix NoMethodError in RemoteReader docs(all): provide README.md with "Commit messages" section style(csv): исправление форматирования в bin/csv2json

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

fix(lynx): fix NoMethodError in RemoteReader Closes #65

Как правильно составлять описания коммитов и почему это важно

Как правильно составлять описания коммитов и почему это важно главное изображение

Заглянув в историю изменений (коммитов) какого-то рандомного Git-репозитория, вы наверняка заметите, что описания коммитов (commit messages) написаны в той или иной степени беспорядочно. Например, посмотрите на описания коммитов, которые я написал, когда начинал контрибьютить в Spring:

$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009" e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build. 2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests) 147709f Tweaks to package-info.java files 22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils 7f96f57 polishing

Выглядит не очень привлекательно. Теперь посмотрите на описания более поздних коммитов в том же репозитории.

$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014" 5ba3db6 Fix failing CompositePropertySourceTests 84564a0 Rework @PropertySource early parsing logic e142fd1 Add tests for ImportSelector meta-data 887815f Update docbook dependency and generate epub ac8326d Polish mockito usage

Бесплатные курсы по программированию в Хекслете

Освойте азы современных языков программирования
Изучите работу с Git и командной строкой
Выберите себе профессию или улучшите навыки

Какие из этих описаний вы прочитаете охотнее? Старые отличаются по форме и по длине, а новые более лаконичные и однообразные. Старые как будто написаны хаотично и без системы, а новые явно писались осознанно и по упорядоченным правилам.

Как я уже говорил, примеры беспорядочных описаний можно найти в историях изменений разных репозиториев. Но есть приятные исключения, например, репозитории ядра Linux и самого Git .

Контрибьюторы этих репозиториев понимают, что правильно оформленные описания — лучший способ передать контекст коммита другим контрибьюторам, а также будущему себе. Диф помогает понять, что именно меняет коммит. Но только описания коммитов помогут понять, зачем это меняется. Важность этого момента хорошо объясняет разработчик Петер Хуттерер (Peter Hutterer) в своём посте . Вот ключевая цитата из него:

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

Если вы не задумывались, зачем нужны правильные описания коммитов, то наверняка вы не очень часто пользовались командой git log . Фактически, это порочный круг: из-за беспорядка в истории коммитов разработчики не хотят заглядывать в неё или заботиться о корректности собственных описаний коммитов. А история остаётся беспорядочной и неудобной, потому что разработчики не пользуются ей и не заботятся о корректности описаний коммитов.

Но правильно оформленная история коммитов — полезная и удобная вещь. Здесь вам пригодятся комманды git blame , revert , rebase , log , shortlog и так далее. С правильно оформленной историей изменений просмотр коммитов других разработчиков приобретает смысл. Кстати, при правильном оформлении истории изменений разобраться в ней можно самостоятельно, не привлекая к этой задаче авторов других коммитов. Вы получаете возможность понять, почему были внесены те или иные изменения в код несколько месяцев или лет назад.

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

Эта статья о том, как правильно составлять описания коммитов. Это простой способ сделать историю изменений репозитория читабельной и информативной.

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

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

Стиль

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

Контент

Что нужно писать в описании коммита? Чего в нём быть не должно?

Метаданные

Как нужно отмечать ID issue, номера пулреквестов и так далее?

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

Семь правил хорошего описания коммита

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

Отрывок из справочных материалов о git commit :

Хоть это и не обязательное требование, рекомендуется начинать описание коммита со строки длиной до 50 символов, которая обобщает изменения. За ней должна следовать пустая строка, а затем более подробное описание коммита. Текст до пустой строки — это заголовок описания коммита, он может использоваться в разных командах Git. Например, Git-format-patch(1) превращает коммит в электронное письмо, в теме которого используется заголовок описания, а в теле — само описание.

Во-первых, не каждый коммит должен иметь заголовок и описание. Иногда можно ограничиться одной строкой, если изменения очень простые.

in introduction to user guide

В данном случае дополнительная информация не нужна. Если кому-то захочется узнать, какие именно ошибки были исправлены, это можно сделать с помощью комманд git show , git diff или git log -p .

Если вы делаете подобный коммит, удобно воспользоваться опцией -m в git commit :

$ git commit -m "Fix typo in introduction to user guide"

А если коммит требует дополнительного объяснения, которое поможет другим разработчикам получить контекст, нужно делать подробное описание.

(causing its deresolution) and turns it back into a chess game.

Подробные описания коммитов с заголовком и телом неудобно писать с помощью опции -m в командной строке. В этом случае лучше делать описание коммита в редакторе. Если вы ещё не настроили редактор для работы с Git, прочитайте этот раздел документации , а также обратите внимание на наш курс «Настройка окружения».

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

$ git log commit 42e769bdf4894310333942ffc5a15151222a87be Author: Kevin Flynn Date: Fri Jan 01 00:00:00 1982 -0200 Derezz the master control program MCP turned out to be evil and had become intent on world domination. This commit throws Trons disc into MCP (causing its deresolution) and turns it back into a chess game.

А теперь выведем только заголовок с помощью git log —oneline :

$ git log --oneline 42e769 Derezz the master control program

Или с помощью команды git shortlog выведем сгруппированные по авторам коммиты. Здесь снова выводится только заголовок описания:

$ git shortlog Kevin Flynn (1): Derezz the master control program Alan Bradley (1): Introduce security program "Tron" Ed Dillinger (3): Rename chess program to "MCP" Modify chess program Upgrade chess program Walter Gibbs (1): Introduce protoype chess program

В Git есть много других ситуаций, в которых в описании коммита важно иметь заголовок и тело. Но ни в одной ситуации это не работает, если между заголовком и телом описания нет пустой строки.

Правило 2: ограничивайте длину заголовка 50 символами

Это не жёсткое ограничение, а практически полезная рекомендация. Соблюдение этого правила гарантирует читабельность заголовка. Также она заставляет автора коммита задуматься и описать изменения максимально коротко.

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

Пользовательский интерфейс GitHub учитывает эти соглашения. Он предупреждает вас, если длина заголовка превышает 50 символов. А если заголовок превышает 72 символа, он обрезается. Поэтому старайтесь уложиться в 50 символов, а 72 символа считайте красной чертой.

Правило 3: пишите заголовок с прописной (заглавной) буквы

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

Правило 4: не ставьте точку в конце заголовка описания

Это ещё одно простое правило: в конце заголовка точка не ставится. Кстати, лишние знаки пунктуации могут помешать вам уложиться в лимит длины 50 символов, о котором шла речь выше. Правильный пример:

Правило 5: используйте повелительное наклонение в заголовке

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

Сделай уборку
Закрой дверь
Вынеси мусор

Все семь правил из этой статьи сформулированы в повелительном наклонении. Например, «не ставьте точку в конце заголовка», «пишите заголовок с прописной буквы».

Повелительное наклонение может показаться грубым, поэтому мы не очень часто используем его в повседневной жизни. Но оно отлично подходит для заголовков в описаниях коммитов. Кстати, Git сам использует повелительное наклонение, когда делает коммиты от вашего имени. Например, при использовании команды git merge автоматически создаётся такое сообщение:

'myfeature'

А вот сообщение, которое создаётся при использовании команды git revert :

"Add the thing with the stuff" This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

Ещё один пример — сообщение, которое создаётся, когда вы нажимаете кнопку Merge, чтобы принять пулреквест:

#123 from someuser/somebranch

Поэтому использование повелительного наклонения соответствует общепринятым соглашениям Git. Вот несколько примеров заголовков на английском языке:

Refactor subsystem X for readability
Update getting started documentation
Remove deprecated methods
Release version 1.0.0

Повелительное наклонение может казаться немного непривычным, так как в повседневной жизни мы чаще пользуемся изъявительным наклонением. При использовании изъявительного наклонения речь больше похожа на отчёт о произошедших событиях. Заголовки описаний в изъявительном наклонении выглядят так:

Fixed bug with Y
Changing behavior of X

Иногда заголовки просто описывают содержание коммитов:

More fixes for broken stuff
Sweet new API methods

Чтобы раз и навсегда разобраться с заголовками описаний коммитов, запомните правило: хороший заголовок всегда должен по смыслу подходить в качестве окончания такого предложения: «If applied, this commit will (ваш заголовок)». Вот несколько примеров:

If applied, this commit will refactor subsystem X for readability
If applied, this commit will update getting started documentation
If applied, this commit will remove deprecated methods
If applied, this commit will release version 1.0.0
If applied, this commit will merge pull request #123 from user/branch

Обратите внимание, если в заголовке не используется повелительное наклонение, он не подходит по смыслу в качестве окончания предложения:

If applied, this commit will fixed bug with Y
If applied, this commit will changing behavior of X
If applied, this commit will more fixes for broken stuff
If applied, this commit will sweet new API methods

Обязательно использовать повелительное наклонение нужно только в заголовке. В теле описания коммита его можно не использовать.

Правило 6: ограничивайте длину строки в теле описания 72 символами

Git не переносит текст автоматически. Помните об этом и переносите строки вручную.

Рекомендуется ограничивать длину строки 72 символами. Это позволит Git оставить в тексте нужные отступы и уложиться в предельную длину строки 80 символов.

Соблюдать это правило поможет хороший текстовый редактор. Можно легко настроить Vim или другой редактор, чтобы он переносил строки, когда их длина достигает 72 символов.

Правило 7: в теле описания отвечайте на вопросы «что?» и «почему?», а не «как?»

Пример описания ниже отлично показывает, как правильно объяснять, что и почему изменилось.

 Date: Fri Aug 1 22:57:55 2014 +0200 Simplify serialize.h's exception handling Remove the 'state' and 'exceptmask' from serialize.h's stream implementations, as well as related methods. As exceptmask always included 'failbit', and setstate was always called with bits = failbit, all it did was immediately raise an exception. Get rid of those variables, and replace the setstate with direct exception throwing (which also removes some dead code). As a result, good() is never reached after a failure (there are only 2 calls, one of which is in tests), and can just be replaced by !eof(). fail(), clear(n) and exceptions() are just never called. Delete them.

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

Обычно можно не писать, как именно сделаны изменения. Если код настолько сложный, что требует дополнительных пояснений, их можно сделать в комментариях. Сфокусируйтесь на объяснении причин изменений — на том, как всё работало до изменений и что здесь было не так, и на том, как оно работает сейчас.

В будущем другие мейнтенеры поблагодарят вас за это, и, возможно, одним из них будете вы!

Вместо заключения: полезные советы

Полюбите командную строку, используйте её вместо IDE

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

Помните об автодополнении, такая функция есть и в Bash, и в Zsh, и в Powershell. Автодополнение избавляет вас от необходимости запоминать полные команды.

Изучите Git и командную строку на Хекслете У нас есть курс по Git и курс по основам командной строки. Зарегистрированные пользователи могут пройти их бесплатно. Другие бесплатные курсы можно найти по ссылке.

Прочтите книгу Pro Git

Её можно бесплатно скачать по ссылке .