Git
Chapters ▾ 2nd Edition

6.3 GitHub - Сопровождение проекта

Сопровождение проекта

Теперь, когда вы комфортно себя чувствуете при участии в проекте, давайте посмотрим на другую сторону вопроса: создание, сопровождение и адимнистрирование вашего собственного проекта.

Создание нового репозитория

Давайте создадим новый репозиторий для распространения кода нашего проекта. В панели управления справа нажмите кнопку “New repository” или воспользуйтесь кнопкой + на панели инструментов, рядом с вашим именем пользователя как показано на рисунке Выпадающее меню “New repository”..

Раздел ``Your repositories''.
Рисунок 110. Раздел “Your repositories”
Выпадающее меню ``New repository''.
Рисунок 111. Выпадающее меню “New repository”.

Это приведет к открытию формы “new repository”:

Форма ``new repository''.
Рисунок 112. Форма “new repository”

Всё, что в действительности нужно сделать, так это указать название проекта, все остальные поля опциональны. Сейчас, просто нажмите кнопку “Create Repository” и ваш новый репозиторий с названием <пользователь>/<имя_проекта> готов.

Так как в репозитории ещё нет кода, GitHub отобразит инструкции о том как создать совершенно новый репозиторий или подключить существующий Git проект. Здесь мы не будем этого делать; если вам нужно освежить память, воспользуйтесь Основы Git.

Теперь ваш проект хостится на GitHub и вы можете предоставить ссылку на него любому желающему. Все проекты на GitHub доступны как по HTTP https://github.com/<пользователь>/<имя_проекта>, так по SSH git@github.com:<пользователь>/<имя_проекта>. Git может получать и отправлять изменения по обоим указанным ссылкам, при этом производится контроль доступа на основании учётных данных пользователя, осуществляющего подключение.

Note

Обычно, для общедоступного проекта предпочтительнее использовать HTTP ссылки, так как это не требует наличия GitHub аккаунта для клонирования репозитория. При этом, для использования SSH ссылки у пользователя должен быть GitHub аккаунт и его SSH ключ должен быть добавлен в ваш проект. Так же HTTP ссылка полностью совпадает с URL адресом, который пользователи могут вставить в браузер для просмотра вашего репозитория.

Добавление участников

Если вы работаете с другими людьми, которым вы хотите предоставить доступ для отправки коммитов, то вам следует добаить их как “участников”. Если Бен, Джефф и Льюис зарегистрировались на GitHub и вы хотите разрешить им делать “push” в ваш репозиторий, то добавьте их в свой проект. Это предоставит им “push” доступ; это означает, что они будут иметь права доступа как на чтение, так и на запись в проект и Git репозиторий.

Перейдите по ссылке “Settings” в нижней части панели справа.

Ссылка на настройки репозитория.
Рисунок 113. Ссылка на настройки репозитория

Затем выберите “Collaborators” в меню слева. Напишите имя пользователя в поле для ввода и нажмите кнопку “Add collaborator”. Так вы можете добавить неограниченное количество пользователей. Чтобы отозвать доступ, просто нажмите “X” справа от имени пользователя.

Окно участников проекта
Рисунок 114. Участники проекта

Управление запросами на слияние

Сейчас у вас есть проект с некоторым кодом и, возможно, несколько участников с “push” доступом, давайте рассмотрим ситуацию, когда вы получается запрос на слияние.

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

Для последующих примеров предположим, что вы “tonychacon” и создали новый проект для Arduino с названием “fade”.

Email уведомления

Кто-то вносит изменения в ваш код и отправляет вам запрос на слияние. Вы должны получить письмо с уведомлением о новом запросе слияния, которое выглядит как на Email уведомление о новом запросе слияния.

Email уведомление о запросе слияния.
Рисунок 115. Email уведомление о новом запросе слияния

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

Если вы видите строку с текстом git pull <url> patch-1, то это самый простой способ слить удаленную ветку без добавления удаленного репозитория. Это кратко писывалось в Проверка удаленных веток. Если хотите, то можно сначала переключиться в тематическую ветку и только потом выполнить эту команду для изменений запроса слияния.

Другие ссылки, которые представляют интерес, это .diff и .patch ссылки. Как вы догадались, они указывают на версии унифицированной разницы и патча запроса слияния. Технически, вы можете слить изменения из запроса слияния командой:

$ curl http://github.com/tonychacon/fade/pull/1.patch | git am

Взаимодействие по запросу слияния

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

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

Email ответ
Рисунок 116. Ответы на письма включены в диалог

Когда вы готовы слить код, вы можете стянуть его себе и слить локально, слить используя команду git pull <url> <branch>, которую мы видели ранее, или добавив ответвленный репозиторий как удаленный получить и слить изменения.

Если слияние тривиально, то можно просто нажать кнопку “Merge” на сайте GitHub. Это всегда приводит с созданию коммита слияния, даже если доступно слияние перемоткой вперед. Это значит, что в любом случае создаётся коммит слияния, как только вы нажимаете кнопку “Merge”. Как можно увидеть на Кнопка Merge и инструкции по ручному слиянию запроса, GitHub отображает информацию об этом при вызове подсказки.

Кнопка Merge
Рисунок 117. Кнопка Merge и инструкции по ручному слиянию запроса

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

Pull Request Refs

Если у вас много запросов слияния и вы не хотите добавлять пачку удаленных репозиториев или постоянно делать однократный “pull”, то у GitHub есть хитрый трюк, позволяющий это делать. Этот трюк очень сложный, но полезный и мы рассмотрим его немного позже в Спецификации ссылок.

Фактически, GitHub представляет ветки запросов слияния как псевдо ветки на сервере. По умолчанию, они не копируются при клонировании, а существуют в замаскированном виде и вы можете легко получить доступ к ним.

В качестве примера мы используем низкоуровневую команду ls-remote (часто упоминается как “plumbing” команда, более подробно о ней будет рассказано в Сантехника и Фарфор). Обычно, эта команда не используется в повседневных Git операциях, но сейчас поможет нам увидеть какие ссылки присутствуют на сервере.

Если выполнить её относительно использованного ранее репозитория “blink”, мы получим список всех веток, тэгов и прочих ссылок в репозитории.

$ git ls-remote https://github.com/schacon/blink
10d539600d86723087810ec636870a504f4fee4d	HEAD
10d539600d86723087810ec636870a504f4fee4d	refs/heads/master
6a83107c62950be9453aac297bb0193fd743cd6e	refs/pull/1/head
afe83c2d1a70674c9505cc1d8b7d380d5e076ed3	refs/pull/1/merge
3c8d735ee16296c242be7a9742ebfbc2665adec1	refs/pull/2/head
15c9f4f80973a2758462ab2066b6ad9fe8dcf03d	refs/pull/2/merge
a5a7751a33b7e86c5e9bb07b26001bb17d775d1a	refs/pull/4/head
31a45fc257e8433c8d8804e3e848cf61c9d3166c	refs/pull/4/merge

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

Если репозиторий находится на GitHub и существуют открытые запросы слияния, то эти ссылки будут отображены с префиксами refs/pull/. По сути это ветки, но так как они находятся не в refs/heads/, то они не копируются при клонировании или получении изменений с сервера — процесс получения изменений игнорирует их по умолчанию.

Для каждого запроса слияния существует две ссылки, одна из которых записана в /head и указывает на последний коммит в ветке запроса на слияние. Таким образом, если кто-то открывает запрос на слияние в наш репозиторий из своей ветки bug-fix, которая указывает на коммит a5a775, то в нашем репозитории не будет ветки bug-fix (так как она находится в форке), при этом у нас появится pull/<pr#>/head, которая указывает на a5a775. Это означает, что мы можем стянуть все ветки запросов слияния одной командой не добавляя набор удаленных репозиториев.

Теперь можно получить ссылки напрямую.

$ git fetch origin refs/pull/958/head
From https://github.com/libgit2/libgit2
 * branch            refs/pull/958/head -> FETCH_HEAD

Эта команда указывает Git: “Подключись к origin репозиторию и скачай ссылку refs/pull/958/head”. Git с радостью слушается и выкачивает всё необходимое для построения указанной ссылки, а так же устанавливает указатель на коммит в .git/FETCH_HEAD. Далее, вы можете слить изменения в нужную ветку при помощи команды git merge FETCH_HEAD, однако сообщение коммита слияния будет выглядеть немного странно. Так же это становится утомительным, если вы просматриваете много запросов на слияние.

Существует способ получать все запросы слияния и поддерживать их в актуальном состоянии при подключении к удаленному репозиторию. Откройте файл .git/config в текстовом редакторе и обратите внимание на секцию удаленного репозитория origin. Она должна выглядеть как-то так:

[remote "origin"]
    url = https://github.com/libgit2/libgit2
    fetch = +refs/heads/*:refs/remotes/origin/*

Строка, начинающаяся с fetch =, является спецификацией ссылок (“refspec”). Это способ сопоставить названия в удаленном репозитории и названиями в локальной папке .git. Конкретно эта строка говорит Git: "все объекты удаленного репозитория из refs/heads должны сохраняться локально в refs/remotes/origin". Вы можете изменить это поведение добавив ещё одну строку спецификации:

[remote "origin"]
    url = https://github.com/libgit2/libgit2.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Последняя строка говорит Git: "Все ссылки, похожие на refs/pull/123/head, должны быть сохранены локально как refs/remotes/origin/pr/123". Теперь, если сохранить файл и выполнить команду git fetch, вы получите:

$ git fetch
# …
 * [new ref]         refs/pull/1/head -> origin/pr/1
 * [new ref]         refs/pull/2/head -> origin/pr/2
 * [new ref]         refs/pull/4/head -> origin/pr/4
# …

Все запросы слияния из удаленного репозитория представлены в локальном репозитории как ветки слежения; они только для чтения и обновляются каждый раз при выполнении git fetch. Таким образом, локальное тестирование кода запроса слияния становится очень простым:

$ git checkout pr/2
Checking out files: 100% (3769/3769), done.
Branch pr/2 set up to track remote branch pr/2 from origin.
Switched to a new branch 'pr/2'

Особо внимательные из вас заметили head в конце спецификации, относящейся к удаленному репозиторию. Так же на стороне GitHub существует ссылка refs/pull/#/merge, которая представляет коммит, формируемый при нажатии кнопки “merge” на сайте. Это позволяет вам протестировать слияние перед нажатием этой кнопки.

Запросы слияния на запросы слияния

Pull Requests on Pull Requests

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

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

При открытии запроса на слияние вверху страницы вы увидите меню для выбора целевой и исходной веток. Если нажать кнопку ‘Edit’' справа, то станет доступным выбор не только исходной ветки, а ещё и форка.

Объекты запроса слияния
Рисунок 118. Ручное изменение форка и ветки для запроса слияния

Здесь можно указать вашу новую ветку для слияния с другим запросом слияния или другим форком проекта.

Упоминания и уведомления

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

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

Упоминания
Рисунок 119. Напишите @ для упоминания кого-либо

Так же можно упомянуть пользователя, не указанного в выпадающем списке, но с помощью автодополнения это можно сделать быстрее.

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

Если кто-то будет упомянут в запросе слияния или проблеме, то он автоматически “подписывается” и будет получать уведомления о последующей активности. Вы так же будете подписаны на некоторые уведомления если просто откроете запрос слияния или проблему, станете отслеживать репозиторий или если оставите коментарий. Для прекращения отправки вам уведомлений нажмите кнопку “Unsubscribe”.

Отказ от подписки
Рисунок 120. Отказ от подписки на проблему или запрос слияния

Страница уведомлений

Когда мы говорим “уведомления” в контексте GitHub, мы имеем ввиду способ, которым GitHub пытается связаться с вами в случае возникновения каких-либо событий, настроить который можно несколькими способами. Для просмотра настроек уведомлений перейдите на закладку “Notification center” на странице настроек.

Центр уведомлений
Рисунок 121. Настройки центра уведомлений

Доступны два вида уведомлений: посредствам “Email” и “Web”. Вы можете выбрать один, ни одного или оба, если активно участвуете в событиях отслеживаемых репозиториев.

Web уведомления

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

Центр уведомлений
Рисунок 122. Центр уведомлений

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

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

Email уведомления

Email уведомления - это ещё один способ, которым вы можете получать уведомления от GitHub. Если эта опция включена, то вы будете получать по письму на каждое уведомление. Примеры вы видели в разделах Комментарии, отправленные по электронной почте и Email уведомление о новом запросе слияния. Письма объединяются в цепочки, что очень удобно при использовании соответствующего почтового клиента.

GitHub включает много дополнительных метаданных в заголовки каждого письма, что полезно при настройке различных фильтров и правил сортировки.

Например, если взглянуть на заголовки письма, отправленного Тони в примере Email уведомление о новом запросе слияния, то можно увидеть следующее:

To: tonychacon/fade <fade@noreply.github.com>
Message-ID: <tonychacon/fade/pull/1@github.com>
Subject: [fade] Wait longer to see the dimming effect better (#1)
X-GitHub-Recipient: tonychacon
List-ID: tonychacon/fade <fade.tonychacon.github.com>
List-Archive: https://github.com/tonychacon/fade
List-Post: <mailto:reply+i-4XXX@reply.github.com>
List-Unsubscribe: <mailto:unsub+i-XXX@reply.github.com>,...
X-GitHub-Recipient-Address: tchacon@example.com

Здесь можно увидеть несколько интересных вещей. Если вы хотите выделить или перенаправить письма конкретного проекта или запроса на слияние, то информация, содержащаяся в заголовке Message-ID, предоставляет вам соответствующие сведения в формате <пользователь>/<проект>/<тип>/<идентификатор>. Для задачи вместо “pull” будет указано “issues”.

Заголовки List-Post и List-Unsubscribe, при наличии у вас почтового клиента, который их понимает, позволяют легко написать в список рассылки или отписаться от неё. Это тоже самое, что и нажать кнопку “mute” в веб версии уведомлений или “Unsubscribe” на странице задачи или запроса на слияние.

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

Особенные файлы

Существует несколько особенных файлов, которые GitHub заметит при наличии их в вашем репозитории.

README

Первый - это файл README, он может быть в любом формате, который GitHub в состоянии распознать. Например, это может быть README, README.md, README.asciidoc и так далее. Если GitHub увидит такой файл в вашем исходном коде, то отобразит его на заглавной странице проекта.

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

  • Для чего предназначен проект

  • Инструкции по конфигурации и установке

  • Примеры использования

  • Используемую лицензию

  • Правила участия в проекте

В этот файл можно встраивать изображения или ссылки для простоты восприятия информации.

CONTRIBUTING

Следующий файл - это CONTRIBUTING. Если в вашем репозитории будет файл CONTRIBUTING с любым расширением, то GitHub будет показывать ссылку на него при создании любого запроса на слияние.

Примечание для участников проекта
Рисунок 123. Создание запроса на слияние при наличии файла CONTRIBUTING.

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

Управление проектом

Для одного проекта не так уж и много администраторских действий, но есть несколько стоящих внимания.

Изменение основной ветки

Если вы используете в качестве основной другую ветку, отличную от “master”, и хотите, чтобы пользователи открывали запросы на слияние к ней, то это можно изменить в настройках репозитория на закладке “Options”.

Основная ветка проекта
Рисунок 124. Изменение основной ветки проекта.

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

Передача проекта

Если вы хотите передать проект другому пользователю или организации на GitHub, то это можно сделать нажатием кнопки “Transfer ownership” в настройках репозитория на закладке “Options”.

Передача проекта
Рисунок 125. Передача проекта другому пользователю или организации на GitHub.

Эта опция полезна, когда вы хотите отказаться от проекта, а кто-то другой хочет им заниматься, или когда ваш проект растёт и вы хотите передать его какой-нибудь организации.

Это действие приведет не только к передаче репозитория со всеми его подписчиками и звёздами, но и добавит перенаправление с вашего URL на новый. Кроме этого, изменятся ссылки для клонирования и получения изменений из Git, а не только для веб запросов.