Github — важная часть жизни современного разработчика: он стал стандартом для размещения opensource-проектов. В «2ГИС» мы используем гитхаб для разработки проектов web-отдела и хостинга проектов с открытым кодом.
Хотя большинство из нас пользуются сервисом практически каждый день, не все знают, что у него есть много фишек, помогающих облегчить работу или рутинные операции. Например, получение публичного ключа из URL; отслеживание того, с каких сайтов пользователи приходят в репозиторий; правильный шаринг ссылок на файлы, которые живут в репозиториях гитхаба; горячие клавиши и тому подобное. Цель этой статьи — рассказать о неочевидных вещах и вообще о том, что сделает вашу работу с гитхабом продуктивнее и веселее (я не буду рассматривать здесь работу с API гитхаба, так как эта тема заслуживает отдельной статьи).
Содержание
- Трюки с URL
- Горячие клавиши
- Тикеты и пулл-реквесты
- Github markdown
- Аккаунт
- Работа с репозиториями
- Поиск кода
- Командная строка и Github
- User scripts
- Github-вандализм
- Дополнительные Github-ресурсы
- Полезные ссылки
Трюки с URL
Философия Github — быть простым, но в то же время очень гибким инструментом. Именно по этой причине многие функции недоступны из пользовательского интерфейса, но доступны через URL-параметры.
Доступ к публичным ключам
Если вы настраиваете ssh-доступ коллегам, у которых есть аккаунт на гитхабе, проще всего сделать это с помощью публичных ключей, полученных прямо с Github через URL: https://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): https://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 incomplete item
При сохранении комментария со списком он превращается в полноценный список задач с чекбоксами, которые можно отмечать (при этом соответствующий [x] появляется в markdown-разметке автоматически). Вот хороший пример работы со списками: https://github.com/neovim/neovim/pull/243
В общем, обязательно загляните в справку гитхаба — Github flavored markdown — там есть ещё пара интересных трюков.
Аккаунт
Двухфакторная аутентификация и безопасность
Здесь обсуждать особо нечего — просто включите её, если вы этого ещё не сделали. Эта опция находится в Settings -> Security. Кстати, там же можно посмотреть всю историю действий, связанных с безопасностью аккаунта (список прошлых сессий, ip-адреса и т.п.).
Привязка нескольких почтовых адресов к одному аккаунту
Если вы используете несколько адресов для работы и личной переписки, вам может быть удобно разграничивать их и на уровне git, делая коммиты в рабочие проекты с одним email, а в домашние — с другим. Можно завести специальный ящик для всех коммуникаций на гитхабе. Во всех случаях возникает проблема: метрики сервиса не будут воспринимать коммиты с почтовым ящиком, отличным от того, с которого произошла регистрация. Чтобы избежать этого, укажите все почтовые адреса, которые будут ассоциированы с вашим профилем (Settings -> Emails). Имейте в виду, что актуализация информации займёт некоторое время.
Дополнение от aivus:
Если вы подтвердите эти email'ы, то с их помощью можно будет получить доступ к вашему аккаунту (восстановление пароля). Если же вы хотите сделать просто ассоциацию email'а с вашим аккаунтом без фичи восстановления пароля — просто не подтверждайте этот ящик. Саппорт гитхаба посоветовал сделать именно так.
Сохранённые ответы (Saved replies)
Эта функция особенно полезна для тех, кто часто пишет однотипные комментарии к пулл-реквестам или тикетам. Например, о том, что пулл-реквест должен соответствовать правилам, определённым в contributing.md. Можно сохранить набор ответов и быстро вставлять их через меню редактора Github:
Страница добавления ответов находится здесь: Settings -> Saved replies.
Упоминания (mentions)
Эта популярная функция по механике похожа на упоминания на хабрхабре или в твиттере. При создании комментария введите символ «@» и сразу же после него никнейм пользователя. У упомянутого пользователя на странице оповещений появится соответствующая ссылка на тикет или пулл-реквест, в котором его упомянули.
Упоминания доступны не только для конкретного пользователя, но и для группы пользователей в организации. В этом случае после «@» надо ввести название организации и через слеш название команды — например, @2gis/mamonts. Добавление новой команды доступно через вкладку Teams на главной странице организации.
Ответы на email-оповещения Github
Если у вас в настройках включены email-оповещения, вы можете участвовать в дискуссиях на гитхабе, не выходя из почтового клиента. Если ответить на email, то от имени вашего пользователя на гитхабе будет создан комментарий в соответствующем тикете или пулл-реквесте с содержимым из вашего отправленного письма.
Подписка на публичную активность пользователей
Если вам интересен определённый пользователь на Github, его можно зафолловить (кнопка «Follow» на странице профиля пользователя) и затем видеть его публичную активность (коммиты, комментарии и т.п.) в общем списке на главной странице сайта. Главная страница может показать только срез за три последних дня, поэтому, если вы не хотите пропускать всю активность пользователей, вам пригодятся rss-ленты, на которые можно подписаться с помощью ссылки вида https://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 дальше.
Напоследок вот несколько наиболее интересных ресурсов, которые помогут вам в этом путешествии:
- Cheat-sheet https://github.com/tiimgreen/github-cheat-sheet
- Awesome Github https://github.com/Kikobeats/awesome-github
- Github Cheat Sheet Хабрахабр https://habrahabr.ru/post/219219/
- Git and GitHub Secrets (Zach Holman) http://confreaks.tv/videos/aloharuby2012-git-and-github-secrets
- More Git and GitHub Secrets (Zach Holman) https://vimeo.com/72955426
- https://help.github.com/
Изображение для обложки статьи — the Steroidtocat by James Kang
