Ефективне використання Github


Github — важлива частина життя сучасного розробника: він став стандартом для розміщення opensource-проектів. У «2ГІС» ми використовуємо гитхаб для розробки проектів web-відділу і хостингу проектів з відкритим кодом.

Хоча більшість з нас користуються сервісом практично кожен день, не всі знають, що у нього є багато фішок, які допомагають полегшити роботу або рутинні операції. Наприклад, отримання публічного ключа з URL; відстеження того, з яких сайтів користувачі приходять в репозиторій; правильний шарінг посилань на файли, які живуть в репозиторіях гитхаба; гарячі клавіші тощо. Мета цієї статті — розповісти про неочевидних речах і взагалі про те, що зробить вашу роботу з гитхабом продуктивніше і веселіше (я не буду розглядати тут роботу з API гитхаба, так як ця тема заслуговує окремої статті).

Зміст


Трюки з URL
Філософія Github — бути простим, але в той же час дуже гнучким інструментом. Саме з цієї причини багато функції недоступні для користувача інтерфейсу, але доступні через URL-параметри.

Доступ до публічних ключів

Якщо ви налаштовуєте ssh-доступ колегам, у яких є аккаунт на гітхабі, найпростіше зробити це за допомогою публічних ключів, отриманих прямо з Github через URL: github.com/<user_name>.keys (наприклад, https://github.com/defunkt.keys). Якщо у вас налаштовані CI-процеси з використанням цієї можливості, у вас завжди будуть актуальні публічні ключі.

Доступ до diff'ам і patch'ам

Якщо додати
.diff
або
.patch
в кінець URL-сторінки з комітом або пулл-реквестом, можна отримати цей висновок у форматі unix-утиліт diff або patch (наприклад, URL в такому форматі https://github.com/tars/tars/commit/07902a956da92e6a616a69d3b3f0f9276f0c13fe.diff — зверніть увагу на «.diff» в кінці). Іноді зручно таким чином отримати набір змін не відходячи від каси і відправити його в Slack або email.

Шарінг URL-посилань на файли в репозиторіях

Тут на перший погляд все просто: скопіював посилання на файл з адресного рядка браузера, вставив куди треба. Але, зважаючи динамічної природи проектів, коміти у майстер додаються постійно, вміст файлу в майбутньому може змінитися або файл може бути зовсім вилучений, тому звичайне копіювання адресного рядка браузера тут не підходить. Щоб отримати постійне посилання на поточну версію файлу (permanent link — так називає їх Github), треба замість назви гілки в URL використовувати хеш коміта. Так, це досить незручно, тому хлопці з гитхаба зробили гарячу клавішу. Натисніть «y» при перегляді файлу — URL в браузері буде змінено на permanent link.

Виняток пробільних символів при перегляді diff

Додайте
?w=1
в URL при перегляді різниці файлів, і, якщо відмінності були тільки в прогалинах, це більше не буде відволікати увагу:



Підсвічування певного блоку коду

При перегляді файлу можна клацнути по будь-якій його рядку і відправити кому-небудь посилання на вказане місце. Можна виділити набір рядків, додавши в URL після номера рядка останній номер рядка діапазону через знак «мінус», ось так (зверніть увагу на L30-L32 в кінці URL): github.com/torvalds/linux/blob/9256d5a308c95a50c6e85d682492ae1f86a70f9b/include/uapi/linux/netfilter_bridge/ebt_among.h#L30-L32

Порівняння ревізій гілок в репозиторії

При створенні пулл-реквеста відразу видно, які зміни потраплять в цільову гілку в результаті злиття. Але є неочевидна можливість сторінки порівняння гілок: ми можемо подивитися всі зміни в гілці за певний час, наприклад, за два тижні — https://github.com/github/linguist/compare/master@%7B2week%7D...master. Іноді корисно зробити закладку в браузері на сторінку з порівнянням і, якщо щось йде не так, оперативно перевіряти, що було змінено в коді, наприклад, за останню добу (“master@{1day}...master). Під капотом цієї фічі використовується стандартний git diff, тому можна використовувати будь-який формат часу, який сприймає git. Більше інформації про порівняння гілок, комітів і тому подібного дивіться у документації.

Гарячі клавіші
Особисто я великий фанат хоткея: вони дозволяють економити час при виконанні стандартних дій і розвивають моторику у дітей. У гитхаба багато гарячих клавіш, розповім про найбільш корисних.

Активація нечіткого пошуку файлів

Якщо натиснути «t» при перегляді репозиторію, з'явиться рядок пошуку файлів, в яку можна ввести частину шляху і вибрати необхідний файл, заощадивши хвилини блукання по репозиторія в пошуках.

Швидкий перехід до певної рядку у файлі

Натисніть «
l
» при перегляді файлу з'явиться маленьке вікно для введення номера рядка.

Швидкі переходи до розділів Github

Ці комбінації легко запам'ятати: вони починаються з префікса «g» (go), і наступна за нею буква вказує на місце призначення. gp — перехід до списку пулл-реквестов, gi — список issues, gn — сторінка нотифікацій і так далі.

Цей список гарячих клавіш далеко не повний. Щоб переглянути всі доступні хоткей, натисніть «?».

Тікети і пулл-реквесты
Тікети (issues) і пулл-реквесты — незмінні помічники при веденні проекту. Гитхаб надає безліч засобів для роботи з ними. Можна використовувати систему міток і кожному тікети або пулл-реквесту проставляти відповідні їм ознаки, наприклад, feature, bug, documentation. Також можна створити milestones і вказувати, над яким каптчей в якій версії буде проводитися робота. А ще є кілька цікавих і корисних трюків.

Автоматичне закриття issues з допомогою комітів

Якщо текст коміта, потрапляє в основну гілку репозиторію, містить слова fix/resolve/close в різних вариациях і номер тікета після символу «#», тоді тікет з відповідним номером буде закритий.

Тобто отримати з таким повідомленням:
$ git commit -m "Fix screwup, fixes #12"

призведе до такого результату:



Пошук найулюбленіших пулл-реквестов і тікетів

Ця функція з'явилася відносно недавно, коли гитхаб додав реакції до коментарям. Тепер сортування може враховувати кількість emoji в реакціях. Відповідно, тип emoji для сортування можна вибрати в меню «Sort»:



Github markdown
У гітхабі використовується надмножество markdown-розмітки, яка використовується в коментарях і markdown-файли. З його допомогою можна робити крос-посилання між репозиторіями або issues, створювати to-do списки, робити підсвітку коду.

Крос-посилання

Якщо при створенні тікета (issue) треба згадати іншого тікет, можна ввести знак «#» — з'явиться меню, з якого можна вибрати необхідний тікет; також можна написати номер тікета самостійно. При збереженні коментаря з посиланням відповідне повідомлення з'явиться на сторінці згаданого тікета. Якщо ви згадали інший тікет з приватного репозиторію, згадка буде видно тільки тим, у кого є доступ до цього сховища. При цьому можна зробити посилання не тільки на issue, але і на конкретний отримати, просто вказавши його хеш — Github автоматично перетворить його в правильне посилання.

Підсвічування синтаксису

Для того щоб підсвітити шматок коду у вашій markdown-розмітки, введіть назву мови після потрійний зворотного лапки перед блоком коду і потрійну зворотний лапки в кінці блоку:
``javascript
function fancyAlert(arg) {
if(arg) {
$.facebox({div:'#foo'})
}
}
``


To-do списки

Синтаксис у списку to-do такий:
[x] @mentions, #refs, [links]()
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] "this is an item incomplete

При збереженні коментаря зі списком він перетворюється в повноцінний список завдань з чекбоксами, які можна відзначати (при цьому відповідний [x] з'являється у markdown-розмітці автоматично). Ось хороший приклад роботи зі списками: https://github.com/neovim/neovim/pull/243

Загалом, обов'язково загляньте у довідку гитхаба — Github flavored markdown — там є ще пара цікавих трюків.

Акаунт

Двофакторна аутентифікація та безпека

Тут обговорювати особливо нічого — просто увімкніть її, якщо ви цього ще не зробили. Ця опція знаходиться в Settings -> Security. До речі, там же можна подивитися всю історію дій, пов'язаних з безпекою облікового запису (список минулих сесій, ip-адреси тощо).

Прив'язка декількох поштових адрес до одного облікового запису

Якщо ви використовуєте кілька адрес для роботи та особистого листування, вам може бути зручно розмежовувати їх і на рівні git, роблячи коміти в робочі проекти з одним email, а домашні — з іншим. Можна завести спеціальний ящик для всіх комунікацій на гітхабі. У всіх випадках виникає проблема: метрики сервісу не будуть сприймати коміти з поштовою скринькою, відмінним від того, з якого відбулася реєстрація. Щоб уникнути цього, вкажіть всі поштові адреси, які асоційовані з вашим профілем (Settings -> Emails). Майте на увазі, що актуалізація інформації займе деякий час.

Збережені відповіді (Saved replies)

Ця функція особливо корисна для тих, хто часто пише однотипні коментарі до пулл-реквестам або тикетам. Наприклад, про те, що пулл-реквест повинен відповідати правилам, визначеним в contributing.md. Можна зберегти набір відповідей і швидко вставляти їх через меню редактора Github:



Сторінка додавання відповідей знаходиться тут: Settings -> Saved replies.

Згадки (mentions)

Ця популярна функція з механіки схожа на згадки на хабрхабре або в твіттері. При створенні коментаря введіть символ «@» і відразу ж після нього нікнейм користувача. У згаданого користувача на сторінці повідомлень з'явиться посилання на тікет або пулл-реквест, в якому його згадали.

Згадки доступні не тільки для конкретного користувача, але і для групи в організації. У цьому випадку після «@» треба ввести назву організації і через слеш назва команди — наприклад, @2gis/mamonts. Додавання нової команди доступно через вкладку Teams на головній сторінці організації.

Відповіді на email оповіщення Github

Якщо у вас у налаштуваннях включені email-оповіщення, ви можете брати участь у дискусіях на гітхабі, не виходячи з поштового клієнта. Якщо відповісти на email, то від вашого імені користувача на гітхабі буде створено коментар у відповідному тикеті або пулл-реквесте з вмістом з вашого відправленого листа.

Підписка на публічну активність користувачів

Якщо вам цікавий певний користувач на Github, його можна зафолловіть (кнопка «Follow» на сторінці профілю користувача) і потім бачити його публічну активність (коміти, коментарі тощо) в загальному списку на головній сторінці сайту. Головна сторінка може показати тільки зріз за три останніх дні, тому, якщо ви не хочете пропускати всю активність користувачів, вам знадобляться rss-стрічки, на які можна підписатися за допомогою посилання виду github.com<user_name>.atom. Таким же чином можна підписатися на всю публічну активність організації (наприклад, https://github.com/2gis.atom).

Робота з репозиторіями

Службові директорії і файли Github

Якщо в корені вашого проекту є readme-файл, його вміст буде відображатися під списком файлів. Це знають багато. Але не всі знають, що якщо створити файл contributing.md з рекомендаціями щодо поліпшення проекту, посилання на нього буде доступна на сторінці створення пулл-реквеста або відкриття тікета:



Після закриття code.google.com безліч проектів переїхало на Github. У зв'язку з цим на гитхаб посипалося безліч запитів з покращення сервісу (так, це всього лише мої здогади, але не виключено, що це подія в якійсь мірі послужило каталізатором). Одним із запитів було створення шаблонів при відкритті тікетів. Нещодавно гитхаб реалізував.

Створіть всередині кореня проекту файл з назвою ISSUE_TEMPLATE, і його вміст буде автоматично вставлятися у поле для вводу при відкритті нового тікета. Те ж саме працює і для пул-реквестов, в цьому випадку файл повинен називатися PULL_REQUEST_TEMPLATE. Файли можуть бути у форматі markdown.

Ось приклад шаблону з репозиторію React — https://github.com/facebook/react/blob/20bcabb1ea4cf492ade240bd6915b4bd44f04895/.github/ISSUE_TEMPLATE.md. Якщо спробувати відкрити тікет в їх репозиторії, поле для введення тексту вже буде заповнено корисною інформацією:



Щоб сильно не засмічувати корінь проекту службовими файлами, можна створити директорію .github/ і помістити всі файли, пов'язані з Github, туди. Всі функції, пов'язані з цими файлами, будуть працювати так само, як раніше.

Статистика мов програмування

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



Якщо ви використовуєте в своєму проекті якийсь великий js-фреймворк і не хочете, щоб він з'їв 70% у вашого коханого Go/Python/Java/Ruby у статистичних даних репозиторію, створіть директорію vendors і покладіть туди всі залежності, які не повинні враховуватися системою статистики гитхаба. Або перевірте наявність того файлу або директорії, від якого ви хочете позбутися статистистических даних тут — цілком можливо, що вам вже нічого не треба робити

Так, якщо мови у проекті визначаються не так, як треба, то в цьому випадку варто подивитися в linguist. Linguist — це ruby-бібліотека, з допомогою якої гитхаб збирає статистику по використовуваних мов. В readme проекту описані різні способи заміщення визначається файлу.

Метрики репозиторію

Гитхаб надає безліч показників для відстеження роботи, яка відбувається в репозиторії. Відповідні інструменти моніторингу знаходяться на вкладках Pulse і Graph. Pulse показує, що відбувалося в репозиторії в певний період часу. У розділі Graph різні показники відображені у вигляді графіків. У власників репозиторіїв у вкладці Graph також з'являється підпункт Traffic. За великим рахунком це міні google analytics для репозиторію: в ньому можна відстежувати, скільки користувачів було у вашому репозиторії і звідки вони прийшли.

Створення нового репозиторію

При створенні репозиторію можна відразу вибрати, який gitignore-файл необхідний, яка ліцензія проекту і потрібна заготівля для readme-файл. Так ви заощадите трохи часу на початковій стадії підготовки проекту:



Якщо вашого типу проекту немає в списку gitignore, тоді слід цю ситуацію поліпшити і запропонувати пулл-реквест в репозиторій gitignore гитхаба.

Пошук коду
Ще одна неочевидна можливість гитхаба — просунутий пошук коду за всіма репозиториям: https://github.com/search:



Як і в будь-якому серйозному пошуковому сервісі, можна перейти на сторінку розширеного пошуку і вказати додаткові параметри: наприклад, ім'я користувача, дату створення, мова, на якій написаний код.

При пошуку діють обмеження, які варто враховувати, якщо ви ведете проект на гітхабі і хочете, щоб сервіс міг проіндексувати ваш код (або, навпаки, якщо не хочете): індексується тільки головна гілка репозиторію (зазвичай це master); індексуються тільки ті файли, які менше 384 KB; індексуються тільки ті сховища, в яких менше 500 000 файлів.

Командний рядок і Github

Hub

Hub — це консольна утиліта від творців гитхаба (git + hub = github), мета якої полегшити використання сервісу з шелла. По суті, hub обертає стандартний git і надає додаткові команди для роботи з репозиторіями, пулл-реквестами і тікетами.

Ось так можна скопіювати репозиторій:
$ hub clone github/hub

Зробити форк:
$ hub fork

Відкрити пулл-реквест:
$ hub pull-request

Автори утиліти радять після установки зробити аліас на hub при виклику git (alias git=hub), так як команди hub не конфліктують зі стандартними командами git.

Більше інформації по роботі з утилітою можна знайти в man або на сайті проекту.

Пулл-реквесты вже у вашому репозиторії

Цікавий момент, про який знають деякі. При створенні пулл-реквеста всі містяться в ньому зміни автоматично потрапляють у ваш репозиторій, так як пулл-реквест за великим рахунком — особлива гілка. Завдяки цій можливості гитхаб може показувати зміни в пулл-реквесте, навіть якщо вихідний форк був видалений. Таким чином, у вас завжди є до них доступ. Щоб зміни з пулл-реквеста потрапили в нову гілку (new_branch), треба виконати команду:
$ git fetch origin pull/<pr_num>/head:new_branch

де <pr_num> — номер пулл-реквеста з URL.

User scripts
User script — це користувальницький JavaScript-код, який змінює певний сайт/веб-додаток, змінюючи його зовнішній вигляд та/або додаючи нові функції. Є досить багато скриптів, призначених для роботи з гитхабом. В каталозі багато застарілих скриптів, але серед них трапляються досить сучасні та корисні.

Github Commit Whitespace

Github Commit Whitespace просто додає на сторінку порівнянь посилання, за допомогою якої можна швидко виключити з diff змінені пробільні символи:



Github News Feed Filter

Github News Feed Filter буде особливо корисний тим, хто моніторить (watch) багато активних репозиторіїв/користувачів. Цей скрипт додає на головну сторінку зі стрічкою подій фільтр, що дозволяє відображати тільки интересущую активність:



Github-вандалізм

Gitfiti

Так, це зовсім не про ефективну роботу, а про штуки, які винахідливі розробники використовують для забави. А саме, ось ці квадратики, показують ваш внесок протягом року — contribution graph:



Маніпулюючи git-репозиторієм, додаючи коміти у визначені дати в певній кількості, можна трохи урізноманітнити діаграму. Наприклад, ось так:



Звичайно, ніхто не робить це руками. Для цього існує чудовий генератор діаграм gitfiti, в якому є вбудовані шаблони зображень і можливість використовувати власні.

Заміна автора коміта

В git є можливість виправлення автора коміта через
$ git commit --amend --author="Linus Torvalds <torvalds@linux-foundation.org>"

У результаті отримати в гітхабі буде відображений з новим автором і його аватарки:



Нічого страшного в цьому немає, тим більше що в квітні Github додав перевірку справжності автора коміта за GPG-підписи. Якщо ви бачите слово «verified» поряд з комітом, значить автор коміта саме ця людина, а не хтось інший:



Додаткові Github-ресурси

Рейтинги репозиторіїв

Джерело нових інструментів і бібліотек — сторінка https://github.com/explore. Тут розміщені різні збірки репозиторіїв, репозиторії, які були додані в обране тими людьми, на яких ви підписані, і, звичайно ж, найпопулярніші репозиторії за останній час.

Статус сервісу

Досить рідко, але буває, що гитхаб працює нестабільно. Основний ресурс, де можна дізнатися, що пішло не так — https://status.github.com/. Там можна знайти різні показники, що відображають стан здоров'я гитхаба і сповіщення про перебої в роботі сервісу.

Github pages

Github вміє хостити статичні сайти. Це дуже зручно, якщо вам треба зробити web-документацію для вашого проекту або промо-сайт. Багато використовують гитхаб для ведення особистих блогів. У найпростішому випадку достатньо створити у вашому гитхаб-репозиотрии гілку gh-pages з index.html всередині. Сторінка доступна за адресою у такому форматі: http(s)://.github.io/<project_name> — наприклад, http://2gis.github.io/makeup/. Більше інформації можна знайти на документації.

Gist

Gist — це git-репозиторій без підтримки директорій. Зазвичай його використовують для зберігання шматків коду і чернеток; там також можна знайти повноцінні туторіали та статті. Можна сказати, що це така лайт-версія гитхаба для ваших нотаток будь-якого характеру, з коментуванням, версионированием і можливістю створювати необмежену кількість секретних записів, які будуть доступні для інших користувачів тільки за прямой ссылке.

Gist можна використовувати на сторонніх ресурсах. Багато хто використовує його для підсвічування синтаксису шматків коду в статичних блогах або на Medium. Для отримання коду скрипта gist, який можна вбудувати на сторінку, треба вибрати Embed з меню вибору виду URL на репозиторій:



Dotfiles

http://dotfiles.github.io/ ви можете знайти якісні збірки налаштувань Unix-систем на будь-який смак.

Octodex

А ось на https://octodex.github.com/ просто живе багато октокотов. Нічого більше. КДПВ ми взяли звідти.

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

Наостанок ось кілька найбільш цікавих ресурсів, які допоможуть вам у цій подорожі:


Зображення для обкладинки статті — the Steroidtocat by James Kang
Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.