Как сделать форк репозитория github

Как создать форк репозитория на GitHub

Одна из основных схем работы на GitHub — создание форка.

Время чтения: меньше 5 мин

Открыть/закрыть навигацию по статье

Задача

Скопировать ссылку «Задача» Скопировано

Необходимо поработать в собственной копии (форке) репозитория для внесения изменений в другой репозиторий с помощью пулреквестов.

Готовое решение

Скопировать ссылку «Готовое решение» Скопировано

Нужно сделать всего несколько шагов.

Откройте вкладку «Code» в нужном репозитории и найдите аккордеон, который называется «Fork». Он находится рядом с количеством звёздочек у проекта. Чтобы раскрыть аккордеон, нажмите на стрелку справа от его названия, и в открывшемся блоке выберите пункт «+ Create a new fork». Если создавали форки репозитория раньше, они тоже отобразятся в самом начале этого блока. Тогда можно перейти в них для работы над репозиторием.

После выбора опции с созданием нового форка, откроется новая страница с его настройками. На ней укажите владельца. По умолчанию будет выбран ваш профиль. Также придумайте уникальное имя репозитория в вашем профиле или профиле организации в поле «Repository name». Дополнительно можете переписать оригинальное описание форка и поставить галочку на пункте «Copy the main branch only». Тогда в ваш форк попадёт только основная ветка репозитория. Имя основной ветки не обязательно будет main . В конце нажмите на кнопку «Create fork» под формой.

После нескольких секунд ожидания вы окажетесь на странице репозитория уже в вашем профиле или в вашей организации.

Разбор решения

Скопировать ссылку «Разбор решения» Скопировано

На GitHub принято использовать несколько паттернов организации работы с репозиториями, с которыми обязательно столкнётесь. Один из таких паттернов — использование форков.

Логика работы может быть такая:

1. Пользователь создаёт собственную копию (форк) у себя в профиле.
2. Клонирует репозиторий или работает с ним напрямую в веб-интерфейсе.
3. Вносит изменение в нужной ветке своего форка.
4. Если всё работает как надо, отправляет пулреквест в основной репозиторий.

Другая схема такая:

1. Пользователю нравится продукт, и лицензия позволяет сделать что-то «по-своему».
2. Делает форк от своего имени или от имени организации.
3. Вносит изменения и оставляет их только в своём форке.

Оба паттерна активно используются пользователями GitHub. Например, форками браузера Chromium стали браузеры Chrome, Яндекс Браузер или современный Edge. Многие дистрибутивы Linux рождались как форки ядра или других дистрибутивов данной операционной системы. В мире JavaScript форки тоже не редкость. Например, пакетный менеджер npm имеет более трёх тысяч форков.

Fork на GitHub — что это такое

Продолжаю увлекательное знакомство новичка с сервисом GitHub и с системой контроля версий Git.

Так как имею учетную запись на GitHub, которую регулярно использую, то у меня возник вопрос, который не мог не возникнуть, рано или поздно. Касается он такой темы, как fork.

Не знаю даже, как правильно поступить дальше — попытаться самому описать вопрос, своими словами; или же попытаться сделать вольный перевод статьи на эту тему — Fork A Repo. Но лучше все же расскажу своими словами.

Fork — это копия репозитория

Fork — это вcего навсего копия репозитория. Это тоже самое, что branch в Git. Только на GitHub такой branch называется

fork

— присутствует своя терминология. Само слово fork в переводе означает ответвление. Для того, чтобы воспользоваться

fork

, нужно иметь свою собственную учетную запись на GitHub; и нужно войти под ней на GitHub в момент выполнения

fork

fork

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

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

pull request

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

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

Fork — создание копии репозитория

Давайте от слов перейдем к делу и на практике выполним хотя бы один fork на GitHub. К слову сказать, в приведенной выше статье-оригинале Fork A Repo дается ссылка на репозиторий Spoon-Knife, созданный авторами статьи для учебных целей — научиться работать с fork на GitHub. Вы, уважаемый читатель, также можете свободно воспользоваться им для себя, чтобы научиться пользоваться fork.

Я воспользуюсь другим репозиторием, который выложен в свободном доступе достаточно известным верстальщиком Юрием Артюхом (akella). Ниже привожу шаги по созданию Fork на GitHub.

• захожу на GitHub под своей учетной записью
• перехожу по ссылке github/akella/sass, по которой расположен репозиторий akella/sass

Фактически, теперь я нахожусь в репозитории akella/sass пользователя akella (Юрий Артюх). Об этом красноречиво говорит надпись akella/sass в левом верхнем углу окна браузера. В правом верхнем углу окна браузера нахожу кнопку Fork.

И нажимаю на нее:

Может случиться, что вы, уважаемый читатель, ничего и не заметите. Но это не так на самом деле. Приглядитесь к “главной” надписи — она изменилась с

Инструкция по Git(Hub)

Если Вы хотите помочь в создании губки, у Вас есть какие-то дополнения к API или Вы хотите усовершенствовать наши документы, тогда вам стоит ознакомиться с git и GitHub. Если Вы уже знакомы с этим (forking, branches, issues, pull-requests и commits), просто пропустите этот раздел. Если Вы понятия не имеете, о чем идёт речь, то читайте дальше.

This guide assumes that you’ve read Установка Git and that you’ve already setup your machine with a Git client of your choice.

Основная концепция Git и GitHub

Git позволяет многим разработчикам одновременно разрабатывать одну часть программного обеспечения. GitHub — это веб-сайт, на котором разработчики могут сотрудничать и обмениваться своей работой с другими пользователями. GitHub использует Git для управления указанной работой.

Если вам непонятна лексика Git или GitHub, взгляните на словарную страницу GitHub.

В этом случае у репозитория SpongePowered«имеется две ветки под названием «master и feature 1 и несколько коммитов на обеих ветках.

Давайте рассмотрим общую концепцию — начнём с репозитория. Репозиторий (от англ. repository; сокр. репо) это место, где хранятся файлы проекта. Репозитории SpongePowered хранятся на GitHub. Однако у этого репо есть ограничения доступа, для охраны его от нежелательных и вредоносных изменений. Вы не сможете самостоятельно внести изменения, так как для обычных пользователей репо доступно только для чтения. Сейчас Вы можете задаться вопросом, как же Вам вносить изменения. Для этого существуют форки (forks). Вы можете взять копию репо SpongePowered и вносить необходимые изменения там. По завершении вы можете отправить его на наш репозиторий в качестве запроса (Pull Request, PR). Предложенные вами изменения будут рассматриваться и наши сотрудники сообщат Вам об ошибках или возможности улучшения, и в конечном итоге проведёт слияние запроса (Merge Pull Request).

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

1. Форкнуть репозиторий на Ваш выбор
2. Клонирование его на Ваше устройство
3. Создание новой ветки
4. Внесение необходимых изменений
5. Проверка на работоспособность
6. Фиксация изменений
7. Синхронизация изменений на GitHub
8. Предложение изменений на репо SpongePowered в качестве PR
9. При необходимости внести изменения в PR
10. Команда внедряет ваш PR в ветку master

Подробнее, пожалуйста!

1. Создание форка репозитория

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

Поскольку концепция вам уже известна, мы обсудим детали. Сначала Вам нужно форкнуть репозиторий, куда вы хотите внести изменения. Это можно сделать с помощью GitHub.com, где Вы можете найти кнопку Fork вверху страницы репозитория. После её нажатия GitHub выполнит работу и предоставит Вам клон оригинального репо. Заметьте, что клон теперь находится на ВашGitHubАккаунт/НазваниеКлонированногоРепозитория . Итак, первый шаг завершен.

All branches from the original repository will get forked too, you receive an exact clone of the forked repo.

2. Клонирование форка на Ваше устройство

Now you need to get this fork to your local machine to make your changes. Open the Git Client of your choice ( Установка Git ) and clone your fork to your local machine. The client will ask you for a folder to store everything in. Second step finished, well done!

Most steps can be done via GUI of your choice. If you’re experienced with a command line interface, then you can use it too. Each step will show you the required commands to achieve the desired result.

Alternatively, you can do this via CLI (command line interface, CMD or powershell on windows). Note that you need to create the folder everything is getting cloned to yourself before typing this command:

git clone git://github.com/YourGitHubAccount/ClonedRepoName.git

3. Создание новой ветки

Теперь, когда у вас есть локальный клон Вашего форка, пришло время создать ветку для работы. Ветви были спроектированы таким образом, чтобы они могли одновременно разрабатывать и тестировать различные функции или дополнения, не вызывая проблем и ошибок из-за вмешательства дополнений. Настоятельно рекомендуется не вносить свои изменения в ветку master . Вместо этого создайте новую ветвь самостоятельно (с разумным именем) и внесите изменения туда.

Это означает, что нам нужно сначала создать branch (ветку), так что давайте! Вы можете сделать это через Ваш клиент (где-то должна быть кнопка create branch (создать ветку)), или вы можете использовать CLI с git:

git checkout -b [name_of_your_new_branch] 

This will create a branch with the name of your choice and switch to it. All changes you’re about to make will be on this branch. If you need to switch to another branch (for example master ), just reuse this command. Third step done! Good job so far! To get an overview of your branches, just have a look at your git client or use:

git branch

Теперь пришло время вносить изменения. Для этого можно использовать редактор или IDE, на Ваш выбор.

4. Проверка на работоспособность

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

Для SpongeDocs вы можете просто отправить свой PR. Он будет автоматически собран и отобразит возможные ошибки. Другой вариант — создать документацию локально. Посмотрите на Readme.md в документации для дальнейших инструкций.

5. Применение изменений

When you’re done, you need to bundle them into a single package (a commit ) and get them into the branch. Again, your git client will help you out. Add a meaningful name to your commit and a short description if needed. This can be done via CLI too:

Сначала соберите все файлы и папки, которые вы хотите поместить в коммит:

git add git add

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

git commit

Это откроет текстовое окно, где вы можете добавить сообщение, если пожелаете. Взгляните на сообщение ниже. Вам необходимо запомнить, что ваши коммиты сохранены только локально, не на вашем форке GitHub.

У Вас может быть несколько коммитов в PR. Просто продолжайте и изменяйте всё, что вам нужно, и фиксируйте изменения. Позже Вы сможете объединить коммиты в один.

Шестой шаг завершен. Почти закончили!

6. Отправка на GitHub

Теперь нам нужно внести изменения в Ваш форк на GitHub. Все, что Вы уже сделали, сейчас храниться лишь локально. Как и всегда, вы можете использовать ваш git-клиент для этого (есть кнопка где-то в вашем GUI), или вы можете сделать это через CLI:

git push

В этом случае оно должно выглядеть так:

git push origin feature/YourFeature

7. Предложение изменений на репо SpongePowered в качестве PR

You can either go to your forks page on GitHub.com (there should be a notice at the top of your forks page to guide you), or you can use your GitHub client to create a pull-request. The official GitHub for Win client uses the top right corner of the window for this.

8. Внесение изменений в PR при необходимости

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

9. Ваш PR подключают

Ну вот, всё готово! Отличная работа!

Расширенный Git

Объединение и перемещение

Let’s say you have finished your additions to the repo, and let’s pretend that you made 137 commits while getting it done. Your commit history will certainly look cluttered. It would be a shame if they were all recorded into the repo, wouldn’t it? Too many trivial commits also clutters the project commit history. Fortunately, Git has a nice tool to circumvent this, it’s called a rebase . Rebasing can take your 137 small commits and just turn them into one big commit. Awesome, isn’t it? Instead of reinventing the wheel, we’ll just pass you a link to a very short and easily understandable squashing tutorial:

Это визуальное отображение того, что он делает:

Настройка удалённого репозитория

Naturally the original repo is the direct parent of your fork and your fork is the direct parent of your local clone. However, the original repo isn’t the direct parent of your clone. This isn’t a problem in the first place, but it prevents you from updating your clone to the latest changes on the original repo. If you setup the original repo as a remote (read: «parent») of your clone, you’ll be able to grab all changes made to this repo and apply it to your local clone. Look below to see how grabbing and updating works.

Хорошо. Этот шаг выполняется с помощью CLI, поскольку большинство графических интерфейсов не обладают этой (довольно продвинутой) функциональностью:

git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git

Если вы не уверены, работает ли это по назначению или вы хотите проверить, какие удалённые репо в настоящее время установлены, Вы можете проверить с помощью:

git remote -v

вывод должен выглядеть так:

origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch) upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push) 

Если вы видите предупреждение fatal: The current branch НазваниеВашейВетки has no upstream branch. , тогда ветвь может не находиться на удаленном удаленном сервере. Это может произойти, если вы первый раз отправляете коммит на новую ветвь. Чтобы обновления текущей ветки и установки удалённого upstream, используйте git push —set-upstream origin НазваниеВашейВетки .

Перемещение

Допустим, Вы внесли некоторые изменения в свою желаемую ветку, но в то же время кто-то ещё обновил репо. Это означает, что Ваш форк и Ваш клон устарели. Это не большая проблема, но чтобы избежать проблем при последующем слиянии ваших дополнений, мы настоятельно рекомендуем провести rebase ваших изменений в отношении последних изменений в исходном репо. Если вы еще не настроили удалённый репозиторий, сделайте это до повторной установки.

A successful rebase requires several steps:

1. Загрузка изменений на удалённый репо

Сначала вам нужно получить изменения в удалённый репозиторий. Это (снова) делается через CLI:

git fetch upstream

Это добавит все изменения с удаленного upstream и поместит их во временную ветвь upstream/master .

2. Слияние удалённых изменений локально

Теперь нам нужно выбрать нашу локальную ветвь master :

git checkout master

После этого мы объединим изменения, которые включены в upstream/master , в нашу локальную ветвь master :

git merge upstream/master

Хорошо, вот что у нас получилось:

3. Rebase локальной ветки в обновлённую Master

Следующим шагом является rebase локальной ветви, с которой вы работаете, на место локальной master . Нам нужно переключиться на вашу рабочую ветвь (здесь: feature/yourfeature ), а затем выполнить rebase. Это делается с помощью:

git checkout feature/yourfeature git rebase master

Это перемотает ветку, добавит коммиты из мастера и затем снова применит ваши собственные изменения. Результат выглядит следующим образом:

4. Отправьте всё в Ваш форк

Последнее, что нам нужно сделать, это отправить всё в форк. Если вы уже создали PR, он автоматически обновится:

git checkout master git push -f git checkout feature/yourfeature git push -f

Вы сделали это, потрясающе! Отличная работа!

SpongeDocs v: 8.0.0

Языки Версии stable 7.4.0 6.0.0 5.1.0 Автономное использование Скачать Содействие Исходный код Правка Перевод

6.2 GitHub — Внесение собственного вклада в проекты

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

Создание ответвлений (fork)

Если вы хотите вносить свой вклад в уже существующие проекты, в которых у нас нет прав на внесения изменений путём отправки (push) изменений, вы можете создать своё собственное ответвление (fork) проекта. Это означает, что GitHub создаст вашу собственную копию проекта, данная копия будет находиться в вашем пространстве имён и вы сможете легко делать изменения путём отправки (push) изменений.

Примечание

Исторически так сложилось, что англоязычный термин «fork» (создание ветвления проекта) имел негативный контекстный смысл, данный термин означал, что кто-то повёл или ведёт проект с открытым исходным кодом в другом, отличном от оригинала, направлении, иногда данный термин так же означал создание конкурирующего проекта с раздельными авторами. В контексте GitHub, «fork» (создание ветвления проекта) просто означает создание ветвления проекта в собственном пространстве имён, что позволяет вносить публичные изменения и делать свой собственный вклад в более открытом виде.

Таким образом, проекты не обеспокоены тем, чтобы пользователи, которые хотели бы выступать в роли соавторов, имели право на внесение изменений путём их отправки (push). Люди просто могут создавать свои собственные ветвления (fork), вносить туда изменения, а затем отправлять свои внесённые изменения в оригинальный репозиторий проекта путём создания запроса на принятие изменений (Pull Request), сами же запросы на принятие изменений (Pull Request) будут описаны далее. Запрос на принятие изменений (Pull Request) откроет новую ветвь с обсуждением отправляемого кода, и автор оригинального проекта, а так же другие его участники, могут принимать участие в обсуждении предлагаемых изменений до тех пор, пока автор проекта не будет ими доволен, после чего автор проекта может добавить предлагаемые изменения в проект.

Для того, чтобы создать ответвление проекта, зайдите на страницу проекта и нажмите кнопку «Создать ответвление» («Fork»), которая расположена в правом верхнем углу.

Рисунок 88. Кнопка «Создать ответвление» («Fork»)

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

Рабочий процесс с использованием GitHub

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

Вот как это обычно работает:

1. Создайте форк проекта.
2. Создайте тематическую ветку на основании ветки master .
3. Создайте один или несколько коммитов с изменениями, улучшающих проект.
4. Отправьте эту ветку в ваш проект на GitHub.
5. Откройте запрос на слияние на GitHub.
6. Обсуждайте его, вносите изменения, если нужно.
7. Владелец проекта принимает решение о принятии изменений, либо об их отклонении.
8. Получите обновлённую ветку master и отправьте её в свой форк.

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

Давайте посмотрим, как можно предложить изменения в проект, размещённый на GitHub.

В большинстве случаев можно использовать официальный инструмент GitHub CLI вместо веб-интерфейса GitHub. Инструмент доступен в системах Windows, MacOS и Linux. Посетите страницу GitHub CLI homepage для получения инструкций по установке и использованию.

Создание запроса на слияние

Тони ищет, чего бы запустить на своём новеньком Arduino. Кажется, он нашёл классный пример на https://github.com/schacon/blink.

Рисунок 89. Проект, над которым мы хотим поработать

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

Для начала, нажмите кнопку «Fork», как было сказано выше, чтобы заполучить собственную копию проекта. Мы зарегистрированы на GitHub под именем «tonychacon», так что наша копия окажется по адресу https://github.com/tonychacon/blink , где мы сможем редактировать её. Мы клонируем его, создадим тематическую ветку, внесём необходимые изменения и, наконец, отправим их на GitHub.

$ git clone https://github.com/tonychacon/blink (1) Cloning into 'blink'. $ cd blink $ git checkout -b slow-blink (2) Switched to a new branch 'slow-blink' $ sed -i '' 's/1000/3000/' blink.ino (macOS) (3) # If you're on a Linux system, do this instead: # $ sed -i 's/1000/3000/' blink.ino (3) $ git diff --word-diff (4) diff --git a/blink.ino b/blink.ino index 15b9911..a6cc5a5 100644 --- a/blink.ino +++ b/blink.ino @@ -18,7 +18,7 @@ void setup() < // the loop routine runs over and over again forever: void loop() < digitalWrite(led, HIGH); // turn the LED on (HIGH is the voltage level) [-delay(1000);-]// wait for a second digitalWrite(led, LOW); // turn the LED off by making the voltage LOW [-delay(1000);-] // wait for a second > $ git commit -a -m 'Change delay to 3 seconds' (5) [slow-blink 5ca509d] Change delay to 3 seconds 1 file changed, 2 insertions(+), 2 deletions(-) $ git push origin slow-blink (6) Username for 'https://github.com': tonychacon Password for 'https://tonychacon@github.com': Counting objects: 5, done. Delta compression using up to 8 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done. Total 3 (delta 1), reused 0 (delta 0) To https://github.com/tonychacon/blink * [new branch] slow-blink -> slow-blink

1. Клонируем нашу копию
2. Создаём тематическую ветку
3. Вносим свои изменения
4. Проверяем изменения
5. Фиксируем изменения в тематической ветку
6. Отправляем новую ветку в нашу копию на GitHub

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

Также можно зайти на страницу «Branches», по адресу https://github.com///branches , найти интересующую ветку и открыть запрос оттуда.

Рисунок 90. Кнопка открытия запроса на слияние

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

Также мы видим список коммитов в нашей тематической ветке, «опередивших» ветку master (в данном случае всего один коммит) и предпросмотр всех изменений, вносимых этими коммитами.

Рисунок 91. Страница создания запроса на слияние

После создания запроса на слияние (путём нажатия кнопки «Create pull request» на этой странице) владелец форкнутого проекта получит уведомление о предложенных изменениях со ссылкой на страницу с информацией о запросе.

Примечание

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

Обработка запроса на слияние

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

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

Рисунок 92. Комментирование определённой строки в запросе на слияние

Как только владелец прокомментирует изменения, автор запроса на слияние (а также все подписавшиеся на этот репозиторий) получат уведомления. Далее мы рассмотрим как настроить уведомления, но сейчас, если Тони включил уведомления через электронную почту, он получит следующее письмо:

Рисунок 93. Комментарии, отправленные по электронной почте

Кто угодно может оставлять комментарии к запросу на слияние. На Страница обсуждения запроса на слияние можно увидеть пример, где владелец проекта оставил комментарии как к строке кода, так и в основной секции обсуждения. Как вы могли заметить, комментарии к коду так же приведены в виде обсуждения.

Рисунок 94. Страница обсуждения запроса на слияние

Теперь участник может видеть что ему необходимо сделать для того, чтобы его изменения были приняты. К счастью, это тоже легко сделать. Используя почту, вам потребуется заново отправить свои изменения в список рассылки, а при использовании GitHub вы просто делаете коммит в тематическую ветку и повторяете push, что автоматически обновляет запрос на слияние. На рисунке Финальная стадия запроса на слияние также видно, что в обновлённом запросе на слияние старый комментарий к коду был свёрнут, так как он относится к строке, которая с тех пор изменилась.

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

Рисунок 95. Финальная стадия запроса на слияние

Примечательно, что если вы перейдёте на вкладку «Files Changed» в этом запросе на слияние, то увидите «унифицированную» разницу — это суммарные изменения, которые будут включены в основную ветку при слиянии тематической ветки. В терминологии git diff это эквивалентно команде git diff master…​ для ветки, на которой основан этот запрос на слияние. В Определение применяемых изменений детальнее описан данный тип отличий.

GitHub так же проверяет может ли запрос на слияние быть применён без конфликтов и предоставляет кнопку для осуществления слияния на сервере. Эта кнопка отображается только если у вас есть права на запись в репозиторий и возможно простейшее слияние. По нажатию на неё GitHub произведёт «non-fast-forward» слияние, что значит даже если слияние может быть осуществлено перемоткой вперед, всё равно будет создан коммит слияния.

При желании, можно стянуть ветку и произвести слияние локально. Если эта ветка будет слита в master ветку и отправлена на сервер, то GitHub автоматически закроет запрос на слияние.

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

Примечание
Не только ответвления

Важно отметить, что можно открывать запросы на слияние между двумя ветками в одном репозитории. Если вы работаете над функционалом с кем-то ещё и у вас обоих есть права записи, то вы можете отправить свою тематическую ветку в репозиторий и открыть запрос на слияние в master ветку в рамках одного проекта, что позволит инициировать процедуру проверки кода и его обсуждения. Создание ответвлений проекта не является обязательным.

Продвинутые запросы на слияние

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

Запросы слияния как Патчи

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

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

Например, если вы вернётесь и посмотрите на Финальная стадия запроса на слияние, то увидите, что участник не делал перебазирование своего коммита и не отправлял новый запрос на слияние. Вместо этого были сделаны новые коммиты и отправлены в существующую ветку. Таким образом, если вы в будущем вернётесь к этому запросу слияния, то легко найдёте весь контекст принятого решения. По нажатию кнопки «Merge» целенаправленно создаётся коммит слияния, который указывает на запрос слияния, оставляя возможность возврата к цепочке обсуждения.

Следование за исходным репозиторием

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

Рисунок 96. Запрос имеет конфликты слияния

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

Существует два основных варианта это сделать. Вы можете либо перебазировать свою ветку относительно целевой ветки (обычно, относительно master ветки исходного репозитория), либо слить целевую ветку в свою.

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

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

Предположим, что в примере «tonychacon», который мы использовали ранее, основной автор сделал изменения, которые конфликтуют с запросом на слияние. Рассмотрим это пошагово.

$ git remote add upstream https://github.com/schacon/blink (1) $ git fetch upstream (2) remote: Counting objects: 3, done. remote: Compressing objects: 100% (3/3), done. Unpacking objects: 100% (3/3), done. remote: Total 3 (delta 0), reused 0 (delta 0) From https://github.com/schacon/blink * [new branch] master -> upstream/master $ git merge upstream/master (3) Auto-merging blink.ino CONFLICT (content): Merge conflict in blink.ino Automatic merge failed; fix conflicts and then commit the result. $ vim blink.ino (4) $ git add blink.ino $ git commit [slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \ into slower-blink $ git push origin slow-blink (5) Counting objects: 6, done. Delta compression using up to 8 threads. Compressing objects: 100% (6/6), done. Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done. Total 6 (delta 2), reused 0 (delta 0) To https://github.com/tonychacon/blink ef4725c..3c8d735 slower-blink -> slow-blink

1. Добавляем исходный репозиторий как удалённый с именем upstream .
2. Получаем последние изменения из него.
3. Сливаем основную ветку в нашу тематическую.
4. Исправляем указанный конфликт.
5. Отправляем изменения в ту же тематическую ветку.

Как только это будет сделано, запрос на слияние будет автоматически обновлён и перепроверен на возможность слияния.

Рисунок 97. Запрос слияния без конфликтов

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

Если вы очень хотите перебазировать ветку, чтобы её почистить, то, конечно, вы можете это сделать, но настоятельно не рекомендуется переписывать ветку, к которой уже открыт запрос на слияние. Если другие люди уже стянули её и проделали много работы, то вы столкнётесь со всеми проблемами, описанными в разделе Опасности перемещения главы 3. Вместо этого, отправьте перебазированную ветку в новую на GitHub и откройте новый запрос на слияние, который указывает на предыдущий, затем закройте исходный.

Ссылки

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

Давайте начнём с перекрёстных ссылок для запросов слияния или проблем. Всем запросам слияния и проблемам присваиваются уникальные номера в пределах проекта. Например, у вас не может быть запроса на слияние с номером #3 и проблемы с номером #3. Если вы хотите сослаться на любой запрос слияния или проблему из другого места, просто добавьте # в комментарий или описание. Так же можно указывать более конкретно, если проблема или запрос слияния находятся где-то ещё; пишите username# если ссылаетесь на проблему или запрос слияния, находящиеся в ответвлённом репозитории, или username/repo# если ссылаетесь на другой репозиторий.

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

Рисунок 98. Перекрёстные ссылки в запросе слияния

Когда мы отправим запрос на слияние, то увидим что-то вроде Отображение перекрёстных ссылок в запросе слияния.

Рисунок 99. Отображение перекрёстных ссылок в запросе слияния

Заметьте, что указанная полная ссылка на GitHub была сокращена до необходимого минимума.

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

Рисунок 100. Отображение перекрёстных ссылок в закрытом запросе слияния

Кроме идентификационных номеров, можно ссылаться на конкретный коммит используя SHA-1. Следует указывать полный 40 символьный хеш SHA-1, но если GitHub увидит его в комментарии, то автоматически подставит ссылку на коммит. Как было сказано выше, вы можете ссылаться на коммиты как в других, так и в ответвлённых репозиториях точно так же, как делали это с Проблемами.

GitHub-версия разметки Markdown

Ссылки на другие Проблемы — это лишь часть интереснейших вещей, которые вы можете делать в текстовых полях на GitHub. Для «проблемы» или «запроса слияния» в полях описания, комментария, комментария кода и других вы можете использовать так называемую «GitHub-версию разметки Markdown». Разметка похожа на обычный текст, который основательно преобразуется.

Смотрите Пример написания и отображения текста с разметкой для примера как использовать разметку при написании комментариев и текста.

Рисунок 101. Пример написания и отображения текста с разметкой

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

Списки задач

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

Список задач можно добавить следующим образом:

- [X] Write the code - [ ] Write all the tests - [ ] Document the code

Если добавить этот список в описание запроса на слияние или проблемы, то он будет отображён следующим образом Отображение списка задач в комментарии

Рисунок 102. Отображение списка задач в комментарии

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

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

Рисунок 103. Статистика задач в списке запросов слияния

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

Отрывки кода

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

Для добавления отрывка кода следует обрамить его обратными кавычками.

```java for(int i=0 ; i < 5 ; i++) < System.out.println("i is : " + i); >```

Если вы укажете название языка, как показано на примере, GitHub попробует применить к нему подсветку синтаксиса. Для приведённого примера код будет выглядеть как на Отображение обрамлённого кода.

Рисунок 104. Отображение обрамлённого кода

Цитирование

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

Цитаты выглядят примерно так:

> Whether 'tis Nobler in the mind to suffer > The Slings and Arrows of outrageous Fortune, How big are these slings and in particular, these arrows?

После обработки комментарий будет выглядеть как Пример отображения цитаты.

Рисунок 105. Пример отображения цитаты

Смайлики

Наконец, вы можете использовать смайлики. На GitHub вы можете часто встретить их в комментариях или запросах на слияние. Для них есть даже помощник. Например, если при наборе комментария ввести символ двоеточия : , то будут предложены варианты автодополнения.

Рисунок 106. Автодополнение для смайлов в действии

Смайлы имеют вид :: и могут располагаться в любом месте комментария. Например, вы можете написать что-нибудь вроде этого:

I :eyes: that :bug: and I :cold_sweat:. :trophy: for :microscope: it. :+1: and :sparkles: on this :ship:, it's :fire::poop:! :clap::tada::panda_face:

Такой комментарий будет выглядеть как на Перегруженный смайликами комментарий.

Рисунок 107. Перегруженный смайликами комментарий

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

Примечание

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

Картинки

Технически, картинки не относятся к разметке GitHub, но их использование очень полезно. В дополнение к ссылкам на картинки в комментариях, GitHub позволяет встраивать картинки в комментарии.

Рисунок 108. Перетаскивание картинки для загрузки и встраивания

Если вернуться немного назад к Перекрёстные ссылки в запросе слияния, то над областью редактирования вы увидите небольшую подсказку «Parsed as Markdown». Нажав не неё, вы получите полную подсказку по использованию GitHub разметки.

Поддержание GitHub репозитория в актуальном состоянии

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

This branch is 5 commits behind progit:master.

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

Первый способ не требует конфигурации. Например, если вы сделали форк репозитория https://github.com/progit/progit2.git , то актуализировать ветку master можно следующим образом:

$ git checkout master (1) $ git pull https://github.com/progit/progit2.git (2) $ git push origin master (3)

1. Если вы находитесь на другой ветке — перейти на ветку master .
2. Получить изменения из репозитория https://github.com/progit/progit2.git и слить их с веткой master .
3. Отправить локальную ветку master в ваш форк origin .

Каждый раз писать URL репозитория для получения изменений достаточно утомительно. Этот процесс можно автоматизировать слегка изменив настройки:

$ git remote add progit https://github.com/progit/progit2.git (1) $ git fetch progit (2) $ git branch --set-upstream-to=progit/master master (3) $ git config --local remote.pushDefault origin (4)

1. Добавить исходный репозиторий как удалённый и назвать его progit .
2. Получить ветки репозитория progit , в частности ветку master .
3. Настроить локальную ветку master на получение изменений из репозитория progit .
4. Установить origin как репозиторий по умолчанию для отправки.

После этого, процесс обновления становится гораздо проще:

$ git checkout master (1) $ git pull (2) $ git push (3)

1. Если вы находитесь на другой ветке — перейти на ветку master .
2. Получить изменения из репозитория progit и слить их с веткой master .
3. Отправить локальную ветку master в ваш форк origin .

Данный подход не лишён недостатков. Git будет молча выполнять указанные действия и не предупредит вас в случае, когда вы добавили коммит в master , получили изменения из progit и отправили всё вместе в origin — все эти операции абсолютно корректны. Поэтому вам стоит исключить прямое добавление коммитов в ветку master , поскольку эта ветка фактически принадлежит другому репозиторию.