12 чудових можливостей GitHub

Хоч убийте, не можу придумати жодного вступу, тож...

#1 Редагування коду на GitHub.com

Почну з того, що, як мені здається, і так усім відомо (хоча особисто я не підозрював про це ще тиждень тому). При перегляді будь-якого текстового файлу на сайті GitHub, у будь-якій репозиторії, праворуч зверху можна бачити маленький олівець. Якщо натиснути на ньому, можна буде відредагувати цей файл. Після завершення натисніть Propose file change ("Запропонувати зміну файлу") і GitHub створить розгалуження репозиторію (fork) та запит на внесення змін (Pull Request). Вражаюче, чи не так? Він сам створює fork! Немає потреби робити форк і завантажувати до себе код, вносити локально зміни та відправляти назад на GitHub з Pull Request'ом. Дуже зручно, якщо потрібно внести мінімальні редагування. не зовсім справжній Pull Request

#2 Вставка зображень

Описи проблем не обмежуються лише текстовими коментарями. Чи знаєте ви, що можна вставляти зображення прямо з буфера обміну? При вставці ви побачите його завантаження (безперечно, в "хмара") і перетворення в розмітку для відображення зображення. Витончено!

#3 Форматування коду

Якщо вам потрібно написати блок коду, почніть із трьох зворотних одинарних лапок — і GitHub спробує вгадати, якою мовою програмування ви пишете. Але якщо ви розміщуєте фрагмент коду такими мовами програмування, як Vue, Typescript або JSX, то можете явно вказати мову, щоб підсвічування синтаксису було правильним. Зверніть увагу на ````jsx у першому рядку: ...що забезпечує правильне відображення фрагмента коду: (це поширюється і на Gist, до речі. Якщо вказати для гіста розширення .jsf, підсвічуватиметься синтаксис JSF). Ось список усіх підтримуваних синтаксисів .

#4 Закриття проблем за допомогою "магічних слів" у Pull Request'ах

Допустимо, ви створюєте Pull Request, що виправляє проблему #234. Ви можете вставити текст "виправляє проблему #234" в опис вашого запиту (або будь-якого коментаря до запиту на зміну). Після цього злиття Pull Request'а "автомагічно" закриє проблему. Круто, чи не так? Ось більше інформації про це у документації .

#5 Посилання на коментарі

Чи потрібно вам колись створити посилання на конкретний коментар, а ви не знали, як це зробити? Ці дні давно минули, оскільки я розкрию вам секрет: для створення посилання на коментар потрібно просто натиснути на дату/час поруч із назвою. Дивіться, у gaearon'а тепер є фотка!

#6 Посилання на код

Отже, ви хочете створити посилання на конкретний рядок коду. У такому випадку, спробуйте: клацніть на номері рядка поруч із потрібним кодом у відкритому файлі. Ух ти, бачите? URL змінився, у ньому тепер видно номер рядка! Якщо утримувати клавішу SHIFT і натиснути на номер іншого рядка, то – вуаля! – URL зміниться ще раз, і буде підсвічено діапазон рядків. Цей URL тепер буде вказувати на файл і діапазон рядків. Але зачекайте, він вказує на поточну гілку. А що, якщо файл зміниться? Напевно, вам потрібне, у цьому випадку, постійне посилання на файл у його поточному стані. Я дуже лінивий, так що зробив один знімок екрана для всього вищеописаного: До речі, щодо URL...

#7 Використання URL GitHub як командний рядок

Переміщення GitHub за допомогою UI організовано дуже зручно. Але іноді, щоб потрапити у певне місце, швидше виявиться просто набрати його в URL. Наприклад, якщо мені потрібно перейти в гілку, над якою я працюю і подивитися відмінності від гілки master, я можу просто ввести / compare/ім'я_гілки після імені репозиторію. Після цього я потраплю на сторінку відмінностей для цієї галузі: Але це відмінності від гілки master, якщо ж я працював до цього з гілкою інтеграції, то можу ввести URL /compare/integration-branch...my-branch Для любителів гарячих клавіш: CTRL+L або CMD+L переводить курсор у рядок URL (принаймні у браузерах Chrome та Firefox). Це в поєднанні з автодоповненням браузера значно спрощує переміщення між гілками. Порада від профі: скористайтеся стрілками для переміщення за пропозиціями автодоповнення Chrome і натискайте SHIFT+DELETE, щоб видалити елементи з історії (наприклад, після злиття гілки). (Не знаю, чи буде легше читати ці гарячі сполучення клавіш, якщо ставитиму в них прогалину, ось так SHIFT + DELETE. Але формально "+" не є їхньою частиною, так що мені цей варіант не подобається. Саме через такі речі я і не сплю ночами, Рондо.)

#8 Створення списків проблем

Чи хотіли б ви, щоб у вашому описі проблеми був присутній чекбокс? І чи бажаєте ви, щоб при перегляді проблеми зі списку відображалася елегантна смужка на кшталт "2 з 5"? Ніяких проблем! Створювати інтерактивні кнопки-прапорці можна за допомогою наступного синтаксису:

• [ ] Screen width (integer)
• [x] Service worker support
• [x] Fetch support
• [ ] CSS flexbox support
• [ ] Custom elements

Синтаксис: пробіл, дефіс, пробіл, квадратна дужка, що відкривається, пробіл (або x), квадратна дужка, що закривається, пробіл і які-небудь слова. Після цього ви зможете дійсно ставити/прибирати галочки з цих кнопок! Мені це, чомусь, здається якимось технічним чаклунством. Ви можете ставити галочки! І при цьому вихідний текст змінюється! Страшно подумати, що вони вигадають далі. А якщо ця проблема є на панелі проекту, то там теж буде відображатися хід виконання: Якщо вам незрозуміло, що я маю на увазі під панеллю проекту - читайте нижче. Усього на пару сантиметрів нижче на цій сторінці.

#9 Панелі проектів у GitHub

Для великих проектів я завжди використовував Jira. А для власних проектів я завжди використовував Trello. Обидва ці інструменти мені дуже подобаються. Коли кілька тижнів тому я дізнався, що GitHub пропонує свій власний варіант, прямо на закладці Projects репозиторію, я подумав, що маю сенс продублювати набір завдань, з якими я вже працюю в Trello. А тепер те саме в проекті GitHub: Поступово ваші очі звикнуть до неконтрастного зображення Задля прискорення я додав усе вищезгадане у вигляді нотаток (notes), тобто вони не є "справжніми" проблемами (issues) GitHub. Але потужність управління завданнями в GitHub полягає в інтеграції з рештою репозиторію - так що, ймовірно, краще додати проблеми з репозиторію на панель. Натисніть Add Cards у верхньому правому куті та знайдіть те, що хотіли б додати. Тут знадобиться спеціальний синтаксис пошуку : наприклад, наберіть is:pr is:open і ви зможете перетягнути будь-який відкритий Pull Request на панель або label:bug , якщо потрібно виправити якісь помилки. А ще можна перетворити існуючі нотатки на проблеми. І, нарешті, із форми існуючої проблеми, додати її до проекту у правій панелі. Вона потрапить до списку triage цієї панелі проекту, так що ви зможете вибрати, в який стовпець її помістити Коли опис "таска" знаходиться в тому ж репозиторії, що і код, що реалізує цей таск, це дуже (ооооочень) зручно. Це означає, що через багато років ви зможете виконати команду git blame для будь-якого рядка коду і з'ясувати всю підоплёку завдання, яка до цього рядка привела, без того, щоб відстежувати це все в Jira/Trello/ще де-небудь.

Недоліки

Останні три тижні я експериментував з виконанням всіх завдань у GitHub замість Jira (на маленькому проекті, приблизно в стилі Канбан), і мені це сподобалося. Але я не можу собі уявити це для scrum-проекту, де необхідно оцінювати та підраховувати належним чином швидкість розробки тощо. Хороша новина: у проектів GitHub настільки мало "особливостей", що перехід на іншу систему не займе, у разі чого багато часу. Тож спробуйте, подивимося, наскільки вам сподобається. Не знаю, наскільки це важливо, але я чув про ZenHubта відкрив його вперше 10 хвабон тому. Фактично це розширення GitHub, в якому можна оцінювати проблеми та створювати "epics" та залежності. Там є графіки швидкості розробки та вигоряння; схоже, що це просто приголомшлива річ. Подальше читання: документація GitHub по Projects.

#10 Gwiki

Для неструктурованого набору сторінок – подібного до Вікіпедії – GitHub Wiki (яку я далі називатиму просто Gwiki) просто чудова. Для структурованого набору сторінок – наприклад, як ваша документація – вже не настільки. Відсутня можливість вказати, що "ось ця сторінка - дочірня по відношенню до тієї", немає таких зручних речей, як кнопки "Наступний розділ" і "Попередній розділ". Гензель і Гретель тут би точно заблукали, тому що "хлібних крихт" тут теж немає. (Примітка автора: Ви читали цю історію? Вона просто нелюдська. Двоє юних відморозків вбивають нещасну голодну стареньку, спалюючи її живцем у її власній печі. І звичайно ж, залишаючи незрозуміло комусь повний безлад. Мені здається, саме тому молодь у наші дні пекельно чутлива – у наші дні казки, читані дітям перед сном, недостатньо жорстокі!) панель, щоб змоделювати реальну структуру веб-сайту. Ця бічна панель знаходиться там постійно, хоча поточна сторінка не підсвічується. Посилання доведеться підтримувати вручну, але загалом усе працює чудово. Якщо хочете, можете подивитися : Це навряд чи може змагатися з чимось на зразок GitBook (який використовується в документації Redux ) або зробленим на замовлення веб-сайтом. Але це вже добрих 80% від нього і все просто у вашому репозиторії. Я просто фанат цього. Пропоную: якщо ви вже переросли етап використання одного файлу README.md і вам потрібно кілька різних сторінок для посібників користувача або більш детальної документації, варто зупинитися на Gwiki. Якщо ж відсутність структури/навігації вам заважає, переходьте на щось ще.

#11 GitHub Pages

Можливо, ви вже знали, що GitHub Pages можна використовувати для розміщення статичного сайту. А як не знали, то знаєте тепер. Однак цей розділ присвячений вужчому питанню: використанню Jekyll для створення сайту. У найпростішому варіанті, GitHub Pages + Jekyll можуть візуалізувати файл README.md з використанням приємної теми оку. Наприклад, погляньте на мою сторінку readme з about-github : Якщо натиснути на закладку settings ("налаштування") для цього сайту на GitHub, увімкнути GitHub Pages і вибрати тему Jekyll... То ми отримаємо сторінку в стилі теми Jekyll : Після цього можна створити цілий статичний сайт на основі, головним чином, редагованих файлів розмітки, по суті, перетворюючи GitHub на CMS. Хоча фактично я цього не використав, саме так створюються сайти на фреймворку Bootstrap з використанням React, так що нічого страшного в цьому немає. Зазначу, що на локальній машині повинен бути запущений Ruby (користувачі Windows тут обміняються розуміють поглядами і підуть іншим шляхом, користувачі macOS скажуть: "У чому проблема, ви куди? Ruby - універсальна платформа! Там є система управління пакетами GEMS!") ( Варто зазначити також, що "Агресивний або загрозливий контент або поведінка" в GitHub Pages неприпустимі, тому ви не зможете розмістити там свою версію історії про Гензеля і Гретель).

Моя думка

Чим детальніше я вивчав зв'язку GitHub Pages + Jekyll (для цієї статті), тим більше мені здавалося, що вся ця ідея дивно пахне. Ідея "зробити свій власний веб-сайт із додатком мінімальних зусиль" чудова. Але для роботи над ним все одно потрібний поточний варіант на локальній машині. І для чогось такого "простого" тут дуже багато команд командного рядка. Я швидко переглянув сім сторінок з розділу Getting Started і відчув, що єдине, що тут простого – це я сам. І це я ще навіть не розібрався із простим синтаксисом для головної сторінки або азами простого "Механізму шаблонизації на основі мови Liquid". Краще я напишу веб-сайт самостійно! Якщо чесно, я трохи здивований, що Facebook використовує це для документації React, в той час як вони могли б, ймовірно, формувати сторінки їхньої системи допомоги за допомогою React та виконувати попередню візуалізацію у вигляді статичних HTML-файлів щодня . Все, що їм потрібно – лише знайти спосіб отримувати існуючі файли розмітки так, як якщо б вони надходабо з CMS. А що якщо...

#12 Використання GitHub як CMS

Припустимо, ми маємо веб-сайт з якимось текстом, але нам не хотілося б зберігати цей текст у вигляді HTML-розмітки. Натомість ми хотіли б зберігати десь шматки тексту, щоб їх могли легко редагувати і звичайні користувачі, не розробники. Бажано, з якимось варіантом керування версіями. Можливо, навіть із якоюсь процедурою рецензування. Ось що я пропоную: використовувати файли розмітки, що зберігаються в репозиторії, для зберігання тексту. І використовувати компонент у клієнтській частині, який би витягував ці шматки тексту та відображав їх на сторінці. Я шанувальник React, так що приклад відповідного компонента <Markdown>, який, при заданому шляху до файлу розмітки, витягне його, виконає синтаксичний розбір і візуалізацію у вигляді HTML.

class Markdown extends React.Component {
    constructor(props) {
      super(props);

      // Конечно, вам нужно заменить это на свой URL
      this.baseUrl = 'https://raw.githubusercontent.com/davidgilbertson/about-github/master/text-snippets';

      this.state = {
        markdown: '',
      };
    }

    componentDidMount() {
      fetch(`${this.baseUrl}/${this.props.url}`)
        .then(response => response.text())
        .then((markdown) => {
          this.setState({markdown});
        });
    }

    render() {
      return (
        <div dangerouslySetInnerHTML={{__html: marked(this.state.markdown)}} />
      );
    }
}

(я використовую тут пакет npm marked для синтаксичного аналізу розмітки в HTML) URL вказує на мій репозиторій прикладів, у каталозі /text-snippets якого лежать файли розмітки. (Можна також використовувати API GitHub для отримання контенту , але я сумніваюся, що це вам знадобиться) Використовувати подібний компонент можна так:

const Page = () => (
  <div className="page">
    <div className="about-us">
      <Markdown url="about-us.md" />
    </div>

    <div className="disclaimer">
      <p>A very important disclaimer:</p>

      <Markdown url="disclaimers/home-page-disclaimer.md" />
    </div>
  </div>
);

Так що тепер GitHub грає роль, до певної міри, вашого CMS, для тих шматків тексту, які ви хотіли б розмістити. Наведений вище приклад витягує розмітку тільки після того, як компонент буде завантажений у браузері. Якщо вам потрібен статичний сайт, доведеться візуалізувати його на сервері. Хороша новина! Ніщо не заважає вам витягти всі файли розмітки на сервері (при використанні будь-якої стратегії кешування, що влаштовує вас). Якщо ви вирішите піти цим шляхом, то має сенс скористатися API GitHub, щоб отримати список усіх файлів розмітки в каталозі. Бонус – утиліти GitHub! Я вже давно використовую розширення Octotreeдля браузера Chrome та рекомендую його вам. Не без застережень, але все ж таки рекомендую. Воно відображає зліва панель з деревоподібним уявленням репозиторію, що переглядається. А з цього відео я дізнався про octobox , який також поки що представляється мені дуже непоганою утилітою. Це папка для ваших проблем GitHub. Це все, що вам потрібно знати про нього. Говорячи про кольори, я зробив усі наведені вище знімки екрану у світлій темі, щоб вас не лякати. Але якщо у всьому іншому я віддаю перевагу темним кольорам, то навіщо терпіти мертвенно-блідий GitHub? Тут я використовував поєднання розширення Stylish для браузера Chrome (що вміє застосовувати теми до будь-якого веб-сайту) та стилю GitHub Dark . І на закуску темна тема інструментів розробника GitHub (вбудована, тільки потрібно включити) і тема Atom One Dark для Chrome.

Bitbucket

Строго говорячи, він тут не зовсім доречний, але я просто не можу не згадати Bitbucket. Два роки тому я розпочинав проект та провів півдня за вибором оптимального git-хостингу. Так ось, Bitbucket виграв із суттєвим відривом. Їхній потік рецензування коду пішов далеко вперед від конкурентів (це було задовго до того, як у GitHub з'явилося хоча б поняття рецензента). З того часу GitHub теж обзавівся рецензіями. На жаль, останній рік мені не доводилося використовувати Bitbucket - можливо, вони знову пішли вперед у чомусь. Тому я рекомендую тим, хто відповідає за вибір git-хостингу, звернути увагу і на Bitbucket.

Висновок

От і все! Сподіваюся, що зумів розповісти вам хоча б три раніше незнайомі вам речі. І ще сподіваюся, що ви добре провели час читання моєї статті.