Git Style Guide [RU]

Переводы доступны на следующих языках:

• Chinese (Simplified)
• Chinese (Traditional)
• English
• French
• German
• Greek
• Japanese
• Korean
• Portuguese
• Thai
• Turkish
• Ukrainian

Содержание

1. Ветки
2. Коммиты
3. Сообщения
4. Объединение
5. Другое...

Ветки

• Выбирайте короткие и описательные имена:

  # хорошо
  $ git checkout -b oauth-migration
  
  # плохо - расплывчатое название
  $ git checkout -b login_fix

• Хорошая практика - использовать номера баг-трекеров, (например, GitHub issue) для именования веток. Например:

  # GitHub issue #15
  $ git checkout -b issue-15

• Используйте дефисы для разделения слов.

• Если несколько людей работают над одной функцией, можно сделать командную и персональные ветки. Например:

  $ git checkout -b feature-a/master # командная ветка
  $ git checkout -b feature-a/maria  # Персональная ветка Марии
  $ git checkout -b feature-a/nikita # Персональная ветка Никиты

  При желании можно объеденить персональную ветку с командной (см. "Объединение")

• Удалите ветку после объединения, если не будете её использовать.

  Совет: Находясь на ветке "master" в командной строке выполните следующую команду, чтобы получить список объединённых веток:

  $ git branch --merged | grep -v "\*"

Коммиты

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

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

• Делайте коммиты маленькими. Маленькие, автономные коммиты легче понять и вернуться, если что-то пойдёт не так.

• Коммиты должны быть логически раположены. Например, если коммит X зависит от изменений в коммите Y, тогда коммит Y нужно сделать до коммита X.

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

Сообщения

• Используйте редактор, а не командную строку, для описания коммита:

  # хорошо
  $ git commit
  
  # плохо
  $ git commit -m "Quick fix"

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

• Заголовок (первая строка сообщения) должна кратко, но ёмко описывать изменения. Идеально - не больше 50 символов. Пишите заголовок в повелительном наклонении.

  # хорошо - повелительное наклонение, меньше 50 символов
  Mark huge records as obsolete when clearing hinting faults
  
  # плохо
  fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.

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

  Также нужно оставить ссылки на используемые ресурсы (например, ссылку на соответствующую проблему в трекере ошибок):

  Short (50 chars or fewer) summary of changes
  
  More detailed explanatory text, if necessary. Wrap it to
  72 characters. In some contexts, the first
  line is treated as the subject of an email and the rest of
  the text as the body.  The blank line separating the
  summary from the body is critical (unless you omit the body
  entirely); tools like rebase can get confused if you run
  the two together.
  
  Further paragraphs come after blank lines.
  
  - Bullet points are okay, too
  
  - Use a hyphen or an asterisk for the bullet,
    followed by a single space, with blank lines in
    between
  
  Source http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
  

  Проще говоря, делая коммит, вы должны подумать: "Какая информация понадобится вам?", если вы наткнётесь на этот коммит через год.

• Если коммит A зависит от коммита B, укажите эту зависимость в коммите A. Используйте хэши SHA1, чтобы ссылаться на коммиты.

  Если коммит A решает проблему созданную коммитом B, это стоит указать в коммите A.

• Если коммиты будут склеены, то используйте флаги --squash и --fixup чтобы явно показать свои действия.

  $ git commit --squash f387cab2

  Совет: Используйте флаг --autosquash при перемещении. Отмеченные коммиты будут автоматически сквошены.

Объединение

• Не переписывайте опубликованную историю. История репозитория ценна сама по себе, и очень важно иметь возможность посмотреть всю историю. Если вы опубликуете изменённую историю, то это вызовет проблемы у тех кто уже работает с репозиторием.

• Есть случаи, когда перезапись истории возможна. Например:

  • Вы - единственный, кто пользуется веткой и просматривает её историю.

  • Вы хотите привести в порядок вашу ветку (например, склеить коммиты) и/или перебазировать её на "master", чтобы объединить их.

  Тем не менее, никогда не переписывайте историю "master" ветки или каких-либо других специализированых ветвей (например, CI).

• Сделайте историю чистой и простой. Перед тем, как объединить ветку, удостоверьтесь, что она соответствует руководству по стилю, если это не так измените порядок коммитов, перепишите сообщения и т.д.

• Если ваша ветка включает в себя более одного коммита, не объединяйте её в режиме fast-forward:

  # хорошо
  $ git merge --no-ff my-branch
  
  # плохо
  $ git merge my-branch

Другое...

• Проверяйте ваши коммиты перед тем, как отправить их в удалённый репозиторий.

• Никогда не отправляйте в удалённый репозиторий, наполовину сделанную работу.

• Держите ваши репозитории в хорошей форме, иногда, выполняя задачи по обслуживанию (англ.):

  • git-gc(1)
  • git-prune(1)
  • git-fsck(1)