Руководство по командной разработке с Git

Это руководство по разработке с git написано на основе статьи “Как внедрить свои изменения в ядро Linux”, информации из раздела справки по git и различных техниках, которые популярны в сообществе.

Ветви

• Старайтесь давать ветвям в git короткие, описательные названия:# хорошее название$ git checkout -b oauth-migration# плохое название - слишком расплывчатое$ git checkout -b login_fix

• Для этой цели также прекрасно подойдут разнообразные идентификаторы задач (например, задача, созданная в сервисе Github):# задача №15 в гитхабе$ git checkout -b issue-15

• Если в названии несколько слов, для разделения используйте дефис «-».
• Когда несколько человек одновременно работают над одним функционалом, возможно, было бы удобно создать отдельную ветку на каждого разработчика и общую ветвь, в которой хранятся все изменения, используя такое именование:$ git checkout -b feature-a/master # общая ветка$ git checkout -b feature-a/maria # личная ветка Марии$ git checkout -b feature-a/nick # личная ветка НикаВсе изменения из личных веток будут сливаться в общую, которая по завершению функционала будет, в свою очередь, добавлена в master.

• Если нет необходимости хранить изменения, сделанные в ветке, то после слияния ее необходимо удалить из удаленного репозитория.
• Совет: чтобы просмотреть список ветвей, которые были “слиты” в master, используйте следующую команду:$ git branch --merged | grep -v "\*"

Коммиты

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

Сообщения к коммитам

• Для написания сообщения к коммиту лучше использовать текстовый редактор, а не консоль:# хороший стиль$ git commit# плохой стиль$ git commit -m "Quick fix"Сохранение изменений в консоли заставляет писать сообщения длинной не более одной строки, что в итоги выливается в неинформативные и неоднозначные сообщения к коммиту.
• Сообщение должно быть описательным и лаконичным. В идеале, оно не должно быть более 50 символов и начинаться с большой буквы. Также в конце сообщения не нужно ставить точку, ведь оно, в какой-то степени, является названием  коммита:# хорошее сообщение - начинается с заглавной буквы, длина менее 50 символовПомечаем большие записи устаревшими для устранения ошибок при очистке # плохое сообщениеустранили сообщения об устаревших ActiveModel::Errors когда ActiveRecord используется вне Rails.

• После названия необходимо дать более полное описание изменений, сделанных в коммите. При этом название и описание надо разделить пустой строкой. Описание должно быть ограничено 72 символами, кроме того, в нем нужно пояснить, для чего именно были внесены эти изменения, как это изменение решает поставленную задачу и какие побочные эффекты возможны при этом.
  Кроме того, в описание необходимо включить связанные с коммитом ресурсы (например, ссылку на соответствующую задачу в системе для отслеживания ошибок):Короткое (не более 50 символов) описание.Для необходимости, более детальное объяснение, ограниченное 72 символами. Иногда первая строка коммита трактуется как тема электронного письма, а остальное - какего тело. Пустая линия, которая разделяет "тему" от "тела" письма необходима, иначе такие команды как rebase воспримут их как одну. - Можно использовать ненумерованные списки с точкой, дефисом либо звездочкой в качестве маркера, отделяя при этом пункты пустыми строками.Источник http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.htmlЕсли коммит А зависит от коммита В, то факт этой зависимости должен быть записан в сообщении к коммиту А. Для ссылки на коммиты используйте их хеш. Аналогично, если в коммите А был исправлен баг, допущенный в коммите В, то этот факт также должен быть упомянут в сообщении к коммиту А.

• Если коммит необходимо добавить к другому коммиту, для этого нужно использовать флаги --squash и --fixup:$ git commit --squash f387cab2(Совет: Используйте флаг --autosquash при перемещении ваших изменений. При этом помеченные коммиты будут “слиты” автоматически.)

Слияние изменений

• Не переписывайте историю репозитория, если она уже опубликована. По ней можно понять, что произошло на самом деле. Изменение истории репозитория может обернуться большими проблемами для всех, кто с ним работает.
• Однако есть случаи, в которых изменение истории вполне обоснованно:Вы в одиночку работаете в ветке и ваш код не проходит ревью.Вы хотите “убрать” у себя в ветке (слить некоторые коммиты в один) и переместить изменения в ветку master, чтобы слить эти изменения позже.
• Не нужно переписывать историю ни master, ни каких либо других специальных веток (особенно тех, которые используются серверами непрерывной интеграции).
• Старайтесь поддерживать историю коммитов ясной и простой. Перед слиянием изменений из вашей ветки:Если изменения не соответствуют вышеописанным нормам, то исправьте это (измените порядок следования коммитов, “сожмите” несколько коммитов в один, переформулируйте сообщения). Далее переместите изменения в ветку, в которую необходимо их внедрить:$ git fetch [my-branch]$ git rebase origin/master# а только потом проводите слияние

• Эти команды создают ветку, которую можно присоединить в конец master, что значительно упрощает историю коммитов. (Примечание: этот способ хорошо использовать для проектов с относительно небольшими ветками. В противном случае, более правильным подходом было бы просто провести слияние веток.)
• Если у вас в ветке больше одного коммита, не стоит делать автоматическое слияние:# хороший стиль - коммит со слиянием будет создан$ git merge --no-ff my-branch# плохой стиль$ git merge my-branch

Дополнительные рекомендации

• Существуют различные способы организации командной разработки и у каждого есть свои достоинства и недостатки. Какой подойдет именно вам, зависит от команды, проекта и процесса разработки. Самое важное здесь — это выбрать свой способ и придерживаться его.
• Будьте последовательны. Это относится к организации разработки, но также касается таких вещей, как: сообщения к коммитам, названиям, которые вы даете ветвям, и именам тэгов. Следуйте выбранному стилю по всему репозиторию, так как это улучшает понимание проекта в целом.
• Перед отправкой изменений на удаленный сервер протестируйте ваш функционал. Не нужно отправлять полуготовый продукт.
• Используйте аннотированные метки чтобы отметить релиз продукта или другие важные точки в истории изменений проекта.
• Используйте подписанные метки для личного использования, в качестве “закладок” для коммитов.
• Поддерживайте в вашем репозитории чистоту при помощи выполнения этих команд:git-gcgit-prunegit-fsck

Перевод статьи «Git Style Guide»