Git
Chapters ▾ 2nd Edition

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

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

Тепер, коли ми знаємо, як робити внески до проектів, поглянемо з іншого боку: створення, супроводжування та адміністрування вашого власного проекту.

Створення нового сховища

Створимо нове сховище, до якого ми додамо код нашого проекту. Спочатку натиснемо кнопку “New repository” (нове сховище) праворуч панелі керування, чи за допомогою кнопки + у верхній панелі інструментів біля вашого імені користувача, як можна побачити в “New repository” (нове сховище) у випадному списку..

Область ``Your repositories'' (ваші сховища).
Figure 109. Область “Your repositories” (ваші сховища).
``New repository'' (нове сховище) у випадному списку.
Figure 110. “New repository” (нове сховище) у випадному списку.

Тоді ми потрапимо до форми “нове сховище”:

Форма ``нове сховище''.
Figure 111. Форма “нове сховище”.

Вам треба лише надати проекту ім’я. Усі інші поля зовсім не обов’язкові. Зараз просто натисніть на кнопку “Create Repository” (створити сховище), і бах – у вас вже є нове сховище на GitHub, під назвою <ім’я користувача>/<назва проекту>.

Оскільки у вашому проекті наразі нема коду, GitHub покаже вам інструкції щодо створення абсолютно нового сховища Git, або приєднання існуючого проекту Git. Ми не будемо її тут викладати. Якщо вам необхідно щось з цього пригадати, дивіться Основи Git.

Тепер у вас є проект на GitHub, ви можете дати URL будь-кому, з ким хочете поділитись своїм проектом. Кожен проект на GitHub є доступним через HTTPS за адресою https://github.com/<user>/<project_name>, та через SSH за адресою git@github.com:<user>/<project_name>. Git може отримувати та викладати зміни користуючись обома URL, проте вони мають контроль доступу, що базується на запиті ім’я/паролю користувача.

Note

Часто більш бажано поширювати HTTPS URL публічного проекту, адже тоді користувачу не доведеться мати обліковий запис GitHub щоб зробити клон проекту. Користувачам доведеться мати обліковий запис та відвантажений SSH ключ щоб мати доступ до вашого проекту через SSH. Посилання HTTPS ще можна просто вставити до вашого веб-оглядача, щоб побачити там ваш проект.

Додавання співпрацівників

Якщо ви працюєте з іншими людьми, та бажаєте надати їм право робити коміти, ви маєте додати їх до “співпрацівників” (collaborators). Якщо Бен, Джефф та Луїза усі мають облікові записи на GitHub, та ви бажаєте надати їм доступ на запис до вашого сховища, ви можете додати їх до свого проекту. Це надасть їм можливість робити “push”, тобто вони матимуть доступ і на читання, і на запис до проекту та сховища Git.

Натисніть на посилання “Settings” (налаштування) знизу бокової панелі праворуч.

Посилання на налаштування сховища.
Figure 112. Посилання на налаштування сховища.

Потім виберіть “Collaborators” (співпрацівники) з меню ліворуч. Потім просто наберіть ім’я в поле, та натисніть “Add collaborator.” (додати співпрацівника) Ви можете повторювати це скільки завгодно раз, щоб надати доступ усім, кому ви бажаєте. Якщо вам треба скасувати доступ, просто натисніть на “X” з правого боку рядка потрібного користувача.

Співпрацівники сховища.
Figure 113. Співпрацівники сховища.

Керування Запитами на Пул (Pull Requests)

Тепер у вас є проект з якимось кодом та можливо навіть декілька співпрацівників з доступом на запис, розгляньмо що робити, якщо хтось направив вам Запит на Пул.

Запити на пул можуть надходити або з гілки у форку вашого сховища, або просто з іншої гілки вашого сховища. Єдина різниця, що якщо він з форку, то зазвичай від людей, до гілки яких ви не маєте права викладати зміни та вони не мають права викладати зміни до вашої, а в разі внутрішнього Запиту на Злиття зазвичай обидві сторони мають на це право.

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

Повідомлення електронною поштою

Хтось приходить, змінює ваш код та відправляє вам Запит на Пул. Вам має надійти лист з повідомленням про новий Запит на Пул, що має виглядати як Лист з повідомленням про новий Запит на Пул..

Лист з повідомленням про новий Запит на Пул
Figure 114. Лист з повідомленням про новий Запит на Пул.

Варто звернути увагу на декілька речей у цьому листі. Він включає невелику статистику змін (diffstat) - список файлів, що були змінені в Запиті на Пул, та наскільки вони змінились. Також у ньому є посилання на сторінку GitHub Запиту на Пул. І ще декілька URL, які ви можете використовувати з командного рядка.

Якщо ви помітили рядок з текстом git pull <url> patch-1, то це простий метод злити зміни з віддаленої гілки без необхідності додавати віддалене сховище. Ми швидко це розглянули в Отримання віддалених гілок. Якщо ви бажаєте, то можете створити та перейти до тематичної гілки, а потім виконати цю команду, щоб злити зміни Запиту на Пул.

Інші цікаві посилання це .diff та .patch, які, як ви можете здогадатись, містять Запит на Пул у вигляді об’єднаних змін (unified diff) та патчу. Ви можете злити Запит на Пул навіть так:

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

Співпраця над Запитом на Пул

Як ми вже бачили в Потік роботи GitHub, ви тепер можете спілкуватись з людиною, яка відкрила Запит на Пул. Ви можете коментувати окремі рядки коду, коментувати цілі коміти, чи коментувати весь Запит на Пул, за допомогою GitHub різновиду Markdown.

Щоразу хтось інший коментує Запит на Пул, ви знову будете отримувати лист з повідомленням, отже ви будете знати що відбувається. Кожен з листів буде містити посилання на Запит на Пул саме туди, де щось відбулося, а також ви можете відповісти прямо на лист, і коментар у Запиті на Пул буде створено автоматично.

Відповідь листом
Figure 115. Відповідь на лист включається в переписку на GitHub.

Щойно код стає вам до вподоби та ви бажаєте його злити, ви можете або зробити пул коду та злити його локально, або використати git pull <url> <branch>, як ми бачили раніше, або можете додати форк як віддалене сховище, отримати з нього всі коміти, а потім вже злити зміни.

Якщо злиття тривіальне, ви також можете просто натиснути на кнопку “Merge” (злити) на сайті GitHub. Це зробить злиття “не-швидко-вперед” (non-fast-forward): створить коміт злиття навіть якщо злиття швидко-вперед можливе. Це означає що за будь-яких обставин, щоразу ви натискаєте на кнопку merge, буде створено коміт злиття. Як ви можете побачити на Кнопка злиття та інструкції щодо злиття Запиту на Пул вручну., GitHub надасть вам усю цю інформацію, якщо ви натиснете на посилання вказівки (hint).

Кнопка злиття
Figure 116. Кнопка злиття та інструкції щодо злиття Запиту на Пул вручну.

Якщо ви вирішите не зливати Запит, ви також можете просто закрити Запит на Злиття, про що автора запиту буде повідомлено.

Посилання (Refs) Запитів на Пул

Якщо вам доводиться працювати з багатьма Запитами на Злиття, та ви не бажаєте додавати купу віддалених сховищ чи робити по одному пулу на кожен, є один дотепний засіб, який GitHub вам дозволяє використати. Це дещо складний засіб та ми дещо докладніше розглянемо подробиці того, що відбувається в Специфікація посилань (refspec), проте він може бути доволі корисним.

Насправді GitHub сприймає гілки Запитів на Злиття для сховища як щось на кшталт псевдо-гілок на сервері. Без додаткових дій ви не отримуєте їх при клонуванні, проте вони є в прихованому вигляді та ви можете доволі легко отримати до них доступ.

Щоб це продемонструвати, ми збираємося використати команду низького рівня (часто їх називають команди “plumbing”, про що ми прочитаємо більше в Кухонні та парадні команди) під назвою ls-remote. Ця команда не потрібна при повсякденному використанні Git, проте вона корисна щоб показати нам, які посилання (references) присутні на сервері.

Якщо ми виконаємо цю команду на сховищі “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 (замість 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/head має опинитись у моєму локальному сховищі під 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 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” сайту. Це дозволяє вам протестувати зливання до власно натискання на кнопку.

Запити на Пул до Запитів на Пул

Ви можете відкривати Запити на Пул не тільки до головної (master) гілки, ви насправді можете відкривати Запит на Пул до будь-якої гілки в мережі. Ви дійсно можете навіть відкрити його навіть до іншого Запиту на Пул.

Якщо ви побачили Запит на Пул, що рухається у вірному напрямку, та у вас є ідеє зміни, що залежить від цього запиту, або ви невпевнені, що думка гарна, або у вас просто немає прав на запис до гілки запиту, ви можете відкрити Запит на Пул прямо до неї.

Коли ви відкриваєте Запит на Пул, нагорі сторінки є поле, що задає гілку, до якої ви створюєте запит на пул, та поле, що задає гілку, з якої ви просите взяти зміни. Якщо ви натиснете на кнопку “Edit” (редагувати) праворуч від поля, ви зможете вибрати не тільки гілки, а й форк.

Ціль Запиту на Пул
Figure 117. Вручну змінюємо цільову гілку та форк Запиту на Пул.

Як бачите, доволі просто запросити зливання вашої нової гілки до іншого Запиту на Пул або до іншого форку проекту.

Згадки та повідомлення

У GitHub також є доволі гарна вбудована система повідомлень, яка може бути доречною, якщо у вас є питання чи вам потрібна допомога від конкретних людей чи команд.

У кожному коментарі ви можете набрати символ @ та він почне автодоповнювання імен та імен користувачів людей, що є співпрацівниками цього проекту, чи просто робили до нього внески.

Згадки
Figure 118. Починаємо набирати символ @ щоб когось згадати.

Ви також можете згадати користувача, якого нема в цьому випадному віконці, проте часто це виходить швидше за допомогою автодоповнювача.

Щойно ви зробите коментар зі згадкою користувача, він отримає повідомлення. Тобто це може бути дуже ефективним методом втягнути людей в спілкування, щоб їм не доводилось весь час продивлятись усі дискусії. Дуже часто люди на GitHub запрошують інших з їхньої команди чи компанії щоб переглянути Завдання чи Запит на Пул.

Якщо когось згадують у Запиті на Пул або Завданні, вони стають “підписаними” (subscribed) на них та продовжать отримувати повідомлення щоразу, коли з ними відбувається якась активність. Ви також можете бути підписані до чогось, що ви відкрили, якщо ви слідкуєте за сховищем або якщо ви коментували щось. Якщо ви більше не бажаєте отримувати повідомлення, є кнопка “Unsubscribe” (відписатись) на сторінці, достатньо натиснути на неї, щоб GitHub припинив повідомляти вам про оновлення цієї сторінки.

Відписуємось
Figure 119. Відписуємось від Завдання чи Запиту на Пул.

Сторінка повідомлень

Коли ми кажемо “повідомлення” (notification) тут щодо GitHub, ми маємо на увазі окремий метод, яким GitHub намагається вам повідомити про якісь події. У вас є декілька різних методів їх налаштувати. Якщо ви перейдете до вкладки “Notification center” (центр повідомлень) зі сторінки налаштувань, ви побачите деякі доступні вам опції.

Центр повідомлень
Figure 120. Опції центру повідомлень.

У вас є дві можливості отримувати повідомлення: через “Електронну пошту” або через “Веб” та ви можете вибрати один з них, жодного, або обидва для Запитів/Завдань та для активності в сховищах, за якими ви слідкуєте.

======= Веб повідомлення

Веб повідомлення існують тільки на GitHub і ви можете їх перевіряти виключно на GitHub. Якщо ця опція ввімкнута у ваших налаштуваннях та вам надійшло повідомлення, ви побачите маленьку синю точку над іконкою повідомлень нагорі вашого екрану, як видно на Центр повідомлень.

Центр повідомлень
Figure 121. Центр повідомлень

Якщо ви на неї натиснете, то побачите список усіх ваших повідомлень, згрупованих по проектам. Ви можете фільтрувати повідомлення за проектом, якщо натиснете на його назву в панелі ліворуч. Також ви можете підтвердити повідомлення, якщо натиснете на пташку (checkmark) біля повідомлення, або підтвердити всі повідомлення проекту, якщо натиснете на пташку зверху групи. Також є кнопка приглушення біля кожної пташки, якщо ви на неї натиснете, ви більше не будете отримувати повідомлень про цю тему.

Усі ці інструменти дуже корисні для роботи з великою кількістю повідомлень. Багато досвідчених користувачів GitHub просто вимикають усі поштові повідомлення та працюють з ними виключно через цю сторінку.

Поштові повідомлення

Поштові повідомлення — це інший спосіб обробляти повідомлення GitHub. Якщо вони ввімкнені, ви будете отримувати листа щодо кожного повідомлення. Ми вже бачили їх приклади в Коментарі, що їх відправили як поштові повідомлення та Лист з повідомленням про новий Запит на Пул.. Листи також будуть вірно впорядковані у групи повідомлень, що дуже корисно, якщо ваш поштовий клієнт їх підтримує.

Також у листах від GitHub є чимало вбудованих до заголовків метаданих, що дуже допомагає при створенні особистих фільтрів та правил.

Наприклад, якщо ми подивимось на заголовки листа, що був відправлений до Тоні в Лист з повідомленням про новий Запит на Пул., ми побачимо наступне серед відправлених даних:

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: цей заголовок має формат <користувач>/<проект>/<тип>/<id>. Якби б це було, наприклад, завдання, <тип> був би “issues” замість “pull”.

Поля List-Post та List-Unsubscribe означають, що, якщо ваш поштовий клієнт їх підтримує, ви легко можете написати (post) до списку, або відписатись (unsubscribe) від розсилки. Останнє нічим не відрізняється від використання кнопки “приглушити” (mute) у веб версії повідомлення та від кнопки “Unsubscribe” на сторінці Завдання чи Запиту на Пул.

Також варто сказати, що якщо у вас ввімкнені поштові та веб повідомлення, та ви прочитаєте поштову версію повідомлення, веб версія також буде позначена прочитаною, якщо ваш поштовий клієнт дозволяє зображення.

Особливі файли

Є декілька особливих файлів, що їх присутність у вашому сховищі помічає GitHub.

README (Прочитай мене)

Першим є файл README, який може бути майже будь-якого формату, який GitHub сприймає як текст. Наприклад, це може бути README, README.md, README.asciidoc тощо. Якщо GitHub побачить файл README у вашому коді, він відобразить його на головній сторінці вашого проекту.

Багато команд використовують цей файл для зберігання всієї інформації, яка доречна для когось незнайомого зі сховищем або проектом. Зазвичай це такі речі як:

  • Для чого цей проект

  • Як його конфігурувати та інсталювати

  • Приклад його використання або запуску

  • Ліцензія проекту

  • Як зробити внесок до нього

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

CONTRIBUTING (Як зробити внесок)

Інший особливий файл, на який звертає увагу GitHub, називається CONTRIBUTING. Якщо у вас є файл CONTRIBUTING з будь-яким розширенням, GitHub покаже Відкриття Запиту на Пул, якщо існує файл CONTRIBUTING. коли хтось почне відкривати Запит на Пул.

Повідомлення про інструкцію по взаємодії з проектом
Figure 122. Відкриття Запиту на Пул, якщо існує файл CONTRIBUTING.

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

Адміністрування Проекту

Взагалі-то на GitHub небагато інструментів адміністрування проекту, проте деякі з них можуть бути корисними.

Зміна типової гілки

Якщо ви використовуєте не гілку “master” як головну, тобто гілку, до якої ви бажаєте щоб люди відкривали Запити на Пул, ви можете це змінити на сторінці налаштуваньсвого сховища на вкладці “Options” (опції).

Типова гілка
Figure 123. Зміна типової гілки проекту.

Просто змініть типову гілку в випадному віконці та без окремої вказівки всі головні операції будуть відбуватися над нею, зокрема яку гілку буде отримувати сховище при клонуванні.

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

Якщо ви бажаєте передати проект іншому користувачу або організації на GitHub, для цього є опція “Transfer ownership” (передача власності) наприкінці тої самої вкладки “Options” на сторінці налаштувань вашого сховища.

Передача
Figure 124. Передача проекту іншому користувачу або організації GitHub.

Це корисно якщо ви покидаєте проект та хтось бажає його продовжити, або якщо ваш проект стає більшим і ви бажаєте перемістити його до організації.

Це не тільки переміщує сховище разом з усіма глядачами (watcher) та зірками до іншого місця, а ще й налаштує перенаправлення з вашого URL до нового місця. Також будуть перенаправлені клонування та отримання змін з Git — не тільки веб запити.