46  Контроль версий и совместная работа с помощью Git и Github

В данной главе представлен обзор использования Git для совместной работы. Более подробные самоучители можно найти внизу страницы в разделе Ресурсы.

46.1 Что такое Git?

Git - это программа контроля версий, которая позволяет отслеживать изменения в папке. Ее можно использовать, как опцию “запись исправлений” в Word, LibreOffice или Google docs, но для всех типов файлов. Это одна из наиболее полезных и используемых опций для контроля версий.

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

Подождите, я слышал о Github, это то же самое? - Не совсем, но вы часто используете их вместе, мы вам покажем, как. Вкратце:

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

  • Вы можете использовать Git клиент/интерфейс, чтобы избежать командной строки и выполнить те же действия (как минимум, самые простые и частые).

  • Если вы хтите хранить свою папку на хостинговом веб-сайте для совместной работы, вы можете создать аккаунт в Github, Gitlab, Bitbucket или прочих.

Так что вы можете использовать клиент/интерфейс Github Desktop, который использует Git фоново для управления своими файлами, как локально на своем компьютере, так и удаленно на сервере Github.

46.2 Зачем использовать комбинацию Git и Github?

Использование Git способствует:

  1. Архивированию документированных версий с постепенными изменениями, чтобы вы могли легко вернуться к предыдущему состоянию
  2. наличию параллельных ветвей, т.е. разработке/“рабочих” версий со структурированными способами интегрировать изменения после просмотра

Это может быть сделано локально на вашем компьютере, даже если вы не работаете совместно с другими людьми. Например, бывало ли, что вы:

  • сожалели об удалении раздела кода, поняв через несколько месяцев, что он вам нужен?

  • возвращались к проекту, который был приостановлен, и пытались вспомнить, внесли ли вы сложные модификации в одну из моделей?

  • имели файл model_1.R и еще один файл model_1_test.R и файл model_1_not_working.R, чтобы что-то попробовать?

  • имели файл report.Rmd, файл report_full.Rmd, файл report_true_final.Rmd, файл report_final_20210304.Rmd, файл report_final_20210402.Rmd и ругали себя за навыки архивирования?

Git поможет во всех этих случаях, его стоит изучить.

Однако он становится еще более важным при использовании в сочетании с онлайн репозиторием, таким как Github, чтобы поддерживать совместные проекты. Это способствует:

  • Совместной работе: другие могут рассматривать, комментировать, принимать/отклонять изменения

  • Предоставление доступа к вашему коду, данным, выходным данным и обратной связи от общественности (или в закрытом режиме с вашей командой)

и позволяет избежать ситуаций:

  • “Упс, я забыл отправить последнюю версию, и теперь вам нужно переделывать двухдневную работу над этим новым файлом”

  • Мина, Генри и Умар одновременно работали над одним скриптом и необходимо вручную объединить их изменения

  • Два человека пытаются изменить один и тот же файл в Dropbox и Sharepoint и при этом возникает ошибка синхронизации.

Это звучит сложно, я не программист

Это может быть сложно. Примеры продвинутого использования могут пугать. Однако, как и в случае с R, или даже Excel, вам не обязательно быть экспертом, чтобы пользоваться преимуществами этого инструмента. Узнав небольшое количество фукнций и понятий, вы сможете отслеживать свои изменения, синхронизировать файлы в онлайн репозитории и совместно работать со своими коллегами в краткие сроки.

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

46.3 Настройка

Установка Git

Git - движок, работающий фоном на вашем компьютере, который отслеживает изменения, ветки (версии), слияния и отката. Вы должны сначала установить Git с https://git-scm.com/downloads.

Установка интерфейса (опционально, но рекомендовано)

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

Существует много опций для всех ОС, от более удобных для новичков до более сложных. Хорошие опции для новичков включают панель RStudio Git и Github Desktop, которые мы продемонстрируем в этой главе. Промежуточные (более мощные, но более сложные) опции включают Source Tree, Gitkracken, Smart Git и другие.

Краткое объяснение клиентов Git.

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

Как указано ниже, вам может иногда потребоваться писать команды Git в терминале, таком как панель терминала RStudio (terminal) (вкладка рядом с консолью R), либо в терминале Git Bash.

Учетная запись Github

Создайте бесплатную учетную запись на github.com.

Вам может быть предложено создать двухфакторную аутентификацию с приложением на вашем телефоне. Подробнее читайте в Github документы справки.

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

46.4 Словарь, концепции и базовые функции

Как и при изучении R, необходимо запомнить некоторые понятия, чтобы разобраться в Git. Вот необходимые для начала основы / интерактивный самоучитель. В следующих разделах мы покажем, как использовать интерфейсы , но полезно знать понятия и термины, чтобы построить умственную модель, так как вам она будет нужна при использовании интерфейсов.

Репозиторий

Git репозиторий (“repo”) - папка, которая содержит все подпапки и файлы для вашего проекта (data, code, images, и т.п.) и истории их изменения. Когда вы начинаете отслеживать изменения в репозитории с помощью него, Git создаст скрытую папку, которая содержит информацию по отслеживанию. Типичный репозиторий Git - ваша папка проекта R (см. страницу руководства Проекты R).

Мы покажем вам, как создать (инициировать) репозиторий Git из Github, Github Desktop или Rstudio в следующих разделах.

Commit (коммит)

commit - это образ проекта на определенный момент времени. Когда вы вносите изменение в проект, вам нужно сделать commit, чтобы отслеживать изменения (дельта), внесенные в ваши файлы. Например, если вы изменили несколько строк кода и обновили соответствующий набор данных. Как только ваши изменения будут сохранены, вы их можете объединить в новый “коммит”.

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

Индексированные изменения? Индексировать изменения - добавить их в зону подготовки для следующего коммита. Идея заключается в том, что вы можете детально решить, какие изменения включить в определенный коммит. Например, если вы работали над спецификацией модели в одном скрипте, а потом над рисунком - в другом, будет иметь смысл сделать два разных коммита (будет проще, если вы захотите откатить изменения на рисунке, но не в модели).

Ветви

Ветвь представляет собой независимую линию изменений в репозитории, параллельную, альтернативную версию файлов проекта.

Ветви полезны, чтобы протестировать изменения до того, как они будут включены в основную ветвь, которая, как правило, является основной/финальной/“активной” версией вашего проекта. Когда вы закончите экспериментировать над ветвью, вы можете привнести изменения в вашу основную ветвь, проведя слияние, либо можете удалить ее, если изменения не были успешными.

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

Локальные и удаленные репозитории

Клонировать - это создать копию репозитория Git в другом месте.

Например, вы можете клонировать онлайн репозиторий из Github локально на свой компьютер, либо начать с локального репозитория и клонировать его онлайн на Github.

Когда вы клонировали репозиторий, файлы проекта существуют в двух местах:

  • ЛОКАЛЬНЫЙ репозиторий физически на вашем компьютере. Это то, где вы вносите реальные изменения в файл/код.

  • УДАЛЕННЫЙ, онлайн репозиторий: версии ваших файлов проекта в репозитории Github (или на другом веб хостинге).

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

  • git fetch скачивает новые изменения из удаленного репозитория, но не меняет ваш локальный репозиторий. Представьте себе, что это просто проверка состояния удаленного репозитория.

  • git pull скачивает новые изменения из удаленного репозитория и обновляет ваш местный репозиторий.

  • Когда вы сделали один или несколько коммитов локально, вы можете использовать git push, чтобы передать коммиты на удаленный репозиторий. Это отправит ваши изменения в Github, чтобы другие люди могли их увидеть и скачать, если хотят.

46.5 Начало работы: создание нового репозитория

Существует много способов создать новые репозитории. Вы можете это сделать с консоли, с Github, либо из интерфейса.

Два общих подхода к началу работы:

  • Создать новый проект R из существующего или нового репозитория Github (предпочтительно для новичков), либо
  • Создать репозиторий Github для существующего проекта R

Стартовые файлы

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

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

  • Файл .gitignore - текстовый файл, где каждая строка будет содержать папки или файлы, которые Git следует игнорировать (не отслеживать изменения). Более подробно прочитать и рассмотреть примеры можно тут.

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

Создание нового репозитория в Github

Чтобы создать новый репозиторий, зайдите в Github и найдите зеленую кнопку для создания нового репозитория. Этот пока пустой репозиторий можно клонировать локально на ваш компьютер (см. следующий раздел).

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

Клонирование из репозитория Github

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

Репозиторий Github может быть уже существующим, в нем может быть содержимое, либо это может быть пустой репозиторий, который вы только что создали. В последнем случае, вы по сути создаете репозиторий Github и локальный проект R одновременно (см. инструкции выше).

Примечание: если у вас нет права редактирования репозитория Github, можно сначала сделать ответвление репозитория в свой профиль, а затем продолжить другие действия. Ответвление объясняется в конце данной главы, но мы рекомендуем вам сначала прочитать другие разделы.

Шаг 1: Зайдите в репозиторий Github, кликните на зеленую кнопку “Code” и скопируйте HTTPS clone URL (см. картинку ниже)

Следующий щаг можно выполнить в любом интерфейсе. Мы это проиллюстрируем с помощью Rstudio и Github desktop.

В Rstudio

в RStudio начните новый проект R, кликнув на File > New Project > Version Control > Git

  • Когда выйдет вопрос про адрес репозитория “Repository URL”, вставьте HTTPS URL из Github
  • Присвойте проекту R короткое информативное имя
  • Выберите, где проект R будет сохранен локально
  • Отметьте поле “Open in new session” (открыть в новой сессии) и кликните “Create project” (создать проект)

Вы сейчас находитесь в новом локальном проекте RStudio, который является клоном репозитория Github. Этот локальный проект и репозиторий Github теперь связаны.

В Github Desktop

  • Кликните на File > Clone a repository

  • Выберите вкладку URL

  • Вставьте HTTPS URL из Github в первое поле

  • Выберите папку, в которой вы хотите иметь местный репозиторий

  • Кликните “CLONE” (клонировать)

Новый репозиторий Github из существующего проекта R

Альтернативный сценарий - у вас есть существующий проект R с содержимым и вы хотите создать для него репозиторий Github.

  1. Создайте новый пустой репозиторий Github для проекта (см. инструкции выше)
  2. Клонируйте этот репозиторий локально (см. инструкции HTTPS выше)
  3. Копируйте все содержимое из ранее существовавшего проекта R (коды, данные и т.п.) в новый, пустой, местный репозиторий (например, используйте копировать и вставить).
  4. Откройте свой новый проект в RStudio, зайдите в панель Git. Новые файлы должны регистрироваться как изменения файлорв, теперь они отслеживаются Git. Следовательно, вы можете собирать эти изменения для коммит и передавать их на Github. После передачи репозиторий в Github отразит все файлы.

См. раздел рабочий поток в Github ниже для получения информации об этом процессе.

Как это теперь выглядит?

В RStudio

Как только вы клонировали репозиторий Github в новый проект R, вы теперь увидите в RStudio вкладку “Git”. Эта вкладка появится в той же панели RStudio, что и рабочая среда R (Environment):

Обратите внимание на кнопки, обведенные на изображении выше, поскольку на них мы будем ссылаться позднее (слева направо):

  • Кнопка коммит сохраненные изменения файла в локальной ветви (это откроет новое окно)
  • Синяя стрелка скачать (обновить локальную версию ветви и получить любые изменения, сделанные в удаленной/Github версии этой ветви)
  • Зеленая стрелка выгрузить (отправить коммиты/изменения локальной версии ветви в удаленную/Github версию этой ветви)
  • Вкладка Git в RStudio
  • Кнопка для создания НОВОЙ ветви, используя ту локальную ветвь, которая отображена справа в качестве базовой. Почти всегда требуется ветвь от основной ветви (после того, как вы сначала нажмете скачать для обновления основной ветви)
  • Ветвь, в которой вы работаете в настоящее время
  • Изменения, которые вы внесли в код или другие файлы, появятся ниже

В Github Desktop

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

46.6 Рабочий поток Git + Github

Обзор процесса

Как только вы завершили настройку (описана выше), у вас будет репозиторий Github, который связан (клонирован) с локальным проектом R. Основная ветвь (созданная по умолчанию) - это так называемая “активная” версия всех файлов. Когда вы хотите внести изменения, хорошей практикой будет создать новую ветвь из основной ветви (похоже на “Сделать копию”). Это типичный рабочий поток в Git, поскольку ветвь создать легко и быстро.

Типичный рабочий поток выглядит следующим образом:

  1. Убедитесь, что ваш локальный репозиторий обновлен, если нет - обновите

  2. Зайдите в ветвь, над которой вы до этого работали, либо создайте новую ветвь, чтобы что-либо попробовать

  3. Работайте над файлами локально на своем компьютере, сделайте один или несколько коммитов в этой ветви

  4. Обновите удаленную версию ветви, чтобы внести свои изменения (выгрузите)

  5. Когда вы удовлетворены своей ветвью, вы можете объединить онлайн версию рабочей ветви в онлайн “основную” ветвь, чтобы перенести изменения.

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

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

Вот еще одна схема.

Примечание: до недавних пор использовался термин “мастер” ветвь, но сейчас ее называют “основная” ветвь.

Изображение источник

46.7 Создание новой ветви

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

В Rstudio на панели Git

Убедитесь, что вы находитесь в “основной” ветви, затем кликните на фиолетовую иконку для создания новой ветви (см. рисунок ниже).

  • Вас попросят назвать свою ветвь описательным именем из одного слова (можно использовать нижнее подчеркивание, если нужно).
  • Вы увидите, что локально вы все еще в том же проекте R, но вы уже не работаете в “основной” ветви.
  • Как только новая ветвь будет создана, она также отразится как ветвь на веб-сайте Github

Вы можете визуализировать ветви на панели Git в Rstudio, кликнув на “History” (история)

В Github Desktop

Процесс очень похож, вас попросят задать ветви имя. Потом будет предложение “Publish you branch to Github” (опубликовать вашу ветвь), чтобы новая ветвь появилась также и в удаленном репозитории.

В консоли

Фоново происходит следующее, вы создаете новую ветвь с помощью git branch, затем переходите на ветвь с помощью git checkout (т.е. говорите Git, что следующий коммит будет тут). Из вашего репозитория git:

git branch my-new-branch  # Создаем ветвь new branch
git checkout my-new-branch # Переходим к ветви
git checkout -b my-new-branch # Оба сразу (сокращение)

Для дополнительной информации об использовании консоли, см. раздел команды для Git в конце.

46.8 Сохраняем изменения (Commit)

Теперь вы можете редактировать код, добавлять новые файлы, обновлять наборы данных и т.п.

Каждое изменение отслеживается, как только соответствующий файл будет сохранен. Измененные файлы будут появляться во вкладке RStudio Git, в Github Desktop, либо через использование команды git status в терминале (см. ниже).

Когда вы вносите значительные изменения (например, добавляете или обновляете раздел кода), сделайте паузу и выполните коммит изменений. Представьте себе коммит, как “партию” изменений, объединенных общей целью. Вы всегда можете продолжить пересматривать файл после того, как сделали коммит изменений.

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

В Rstudio

Пример ниже показывает, что с момента последнего коммит, скрипт R Markdown “collaboration.Rmd” изменился, и было добавлено несколько изображений PNG.

Вы возможно задаетесь вопросом, что представляют собой желтые, синие, зеленые и красные квадраты рядом с именами файловю Вот снимок экрана шпаргалки RStudio, которая объясняет их значений. Обратите внимание, что изменения с желтым “?” все еще можно подготовить к коммит, сделать коммит и выгрузить.

  • Нажмите кнопку “Commit” на вкладке Git, которая откроет новое окно (см. ниже)

  • Кликните на имя файла в верхнем левом поле

  • Посмотрите изменения, которые вы внесли в этот файл (ниже выделено зеленым или красным)

  • “Подготовьте” файл, который включает все изменения для коммит. Это можно сделать, отметив поле рядом с именем файла. Альтернативно вы можете выделить несколько имен файлов и потом кликнуть “Stage” (подготовить)

  • Напишите сообщение для коммит, которое будет коротким, но описательным (обязательно)

  • Нажмите кнопку “Commit” (коммит). Появится всплывающее окно, показывающее сообщение о выполнении или ошибке.

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

В Github Desktop

Вы можете увидеть список файлов, которые были изменены, слева. Если вы выберете текстовый файл, вы увидите краткую информацию о модификациях, которые были сделаны, на правой панели (просмотр не сработает для более сложных файлов, таких как .docs или .xlsx).

Чтобы подготовить изменения к коммит, просто отметьте маленькое поле рядом с именем файла. Когда вы выберете файлы, которые вы хотите добавить к коммит, задайте имя для коммит, опционально также описание и затем кликните кнопку commit (коммит).

В консоли

Две функции, работающие фоново, включают git add для выбора/подготовки файлов и git commit, чтобы сделать коммит.

git status # См. изменения 

git add new_pages/collaboration.Rmd  # выбираем файл для коммит (= подготовка к изменениям)

git commit -m "Describe commit from Github Desktop" # коммит изменений с сообщением

git log  # просмотр информации по предыдущим коммитам

Внесение изменений в предыдущий коммит

Что происходит, если вы делаете коммит для изменений, продолжаете работать и понимаете, что внесли изменения, которые должны были “относиться” к прошлым коммитам (на ваш взгляд). Не бойтесь! Вы можете приложить эти изменения к предыдущему коммиту.

В Rstudio это должно быть достаточно очевидно, там есть поле “Amend previous commit” (внести изменения в предыдущий коммит) на той же строке. что и кнопка COMMIT.

По какой-то причине, такой функционал не был внедрен в Github Desktop, но существует (концептуально странный, но легкий) выход. Если вы сделали коммит, но еще не выгрузили ваши изменения, прямо под кнопкой “UNDO” (ОТМЕНИТЬ), появится кнопка COMMIT (КОММИТ). Кликните на нее и она откатит ваш коммит (но сохранит ваши подготовленные файлы и сообщение коммит). Сохраните ваши изменения, добавьте новые файлы в коммит, если необходимо, и снова нажмите коммит.

В консоли:

git add [YOUR FILES] # подготовка новых изменений

git commit --amend  # внесение изменений в прошлый коммит

git commit --amend -m "An updated commit message"  # внесение изменений в прошлый коммит И обновление сообщения для коммит

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

46.9 Скачивание и выгрузка изменений на Github

“Сначала PULL (скачиваем), потом PUSH (выгружаем)”

Хорошей практикой будет получить и скачать до начала работы над проектом, чтобы обновить версию ветви на локальном компьютере, с изменениями, которые были внесены в удаленную/Github версию.

СКАЧИВАЙТЕ часто. Не забывайте. Сначала скачивайте, потом выгружайте.

Когда вносятся ваши изменения и вы делаете коммит, если вы довольны
состоянием вашего проекта, вы можете выгрузить ваши коммиты на удаленную/Github версию своей ветви.

Повторяйте этот процесс при работе в репозитории.

Примечание: гораздо легче откатить изменения, для которых был сделан коммит, но которые не были выгружены (т.е. все еще хранятся локально), чем откатить изменения, которые были переданы в удаленный репозиторий (и их уже кто-то скачал), поэтому лучше выгружать их, когда вы закончили внесение изменений в ту задачу, над которой вы работаете.

В Rstudio

СКАЧАТЬ - сначала нажмите иконку скачать “Pull” (стрелка вниз), которая получает и скачивает одновременно.

ВЫГРУЗИТЬ - Кликните зеленую иконку “Pull” (стрелка вверх). Вас могут попросить ввести свое имя пользователя и пароль Github. Первый раз, когда вас запросят, может потребоваться ввести две командных строки Git в Terminal:

  • git config –global user.email “” (your Github email address), и
  • git config –global user.name “Your Github username”

Чтобы больше узнать о том, как вводить эти команды, см. раздел по командам Git ниже.

СОВЕТ: У вас слишком часто запрашивается пароль? См. главы 10 и 11 данного самоучителя, чтобы подключить репозиторий, используя ключ SSH (более сложно).

В Github Desktop

Кликните на кнопку “Fetch origin” (получить исходник), если есть новые коммиты в удаленном репозитории.

Если Git найдет новые коммиты в удаленном репозитории, кнопка изменится на кнопку “Pull” (скачать). Поскольку та же кнопка используется для скачивания и выгрузки, вы не можете выгрузить изменения, пока их не скачали.

Вы можете зайти во вкладку “History” (история) (рядом со вкладкой “Changes” (изменения)), чтобы увидеть все коммиты (ваши и чужие). Это хороший способ познакомиться с тем, что сделали другие люди, совместно работающие с вами. Вы можете прочитать сообщение коммит, описание - если есть, и сравнить код двух файлов, используя вкладку diff.

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

Консоль

Неудивительно, что команды тут также fetch (получить), pull (скачать) и push (выгрузить).

git fetch  # есть ли новые коммиты в удаленной директории?
git pull   # скачать удаленные коммиты в свою локальную ветвь
git push   # выгрузить локальные коммиты этой ветви в удаленную ветвь

Я хочу скачать, но у меня есть локальная работа

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

Git откажется скачивать, поскольку это может привести к записи поверх ваших изменений. Есть несколько стратегий для сохранения своих изменений, хорошо описанных в Happy Git with R, две из них включают: - коммит ваших изменений, получение удаленных изменений, скачивание, разрешение конфликтов, если необходимо (см. раздел ниже), и выгрузите все онлайн - используйте stash для своих изменений, что по сути позволяет отложить их в сторонку, скачать, вытащить из хранилища (восстановить), затем сделать коммит, устранить конфликты и выгрузить.

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

В Github Desktop это можно сделать с помощью кнопок. Чтобы сделать stash, зайдите в Branch > Stash all changes.

46.10 Присоединение ветви к основной

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

Локально в Github Desktop

Можно произвести объединение ветвей локально, используя Github Desktop. Во-первых, зайдите (к выдаче) ветви, которая будет получателем коммит, иными словами, ветви, которую вы хотите обновить. Затем зайдите в меню Branch > Merge into current branch и кликните. Поле позволит вам выбрать ветку, из которой вы хотите импортировать.

В консоли

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

git checkout master  # вернитесь в мастер (или в ветвь, в которую хотите перенести свою)
git merge this_fancy_new_branch

Эта страница показывает более продвинутый пример разделения на ветви, и немного объясняет, что происходит фоново.

В Github: подача запросов на скачивание

Хотя вполне возможно объединить две ветви локально, или не ставя никого в известность, слияние может обсуждаться или исследоваться несколькими людьми до интеграции в основную ветку. Чтобы помочь в этом процесс, Github предлагает некоторые возможности обсуждения слияния: запросы на скачивание.

Запрос на скачивание (“PR”) - запрос на присоединение одной ветви к другой (иными словами, запрос на то, что ваша рабочая ветвь будет присоединена к “основной” ветви). Запрос на скачивание как правило требует несколько коммитов. Запрос на скачивание, как правило, начинает процесс обсуждения и обзора, прежде чем он будет принят и ветвь будет присоединена. Например, вы можете прочитать обсуждения запросов на скачивание в github dplyr.

Вы можете подать запрос на скачивание (PR) напрямуюна сайте (как показано ниже) или с Github Desktop.

  • Зайдите в репозиторий Github (онлайн)
  • Просмотрите вкладку “Pull Requests” (запросы на скачивание) и кликните на кнопку “New pull request” (новый запрос на скачивание)
  • Выберите из выпадающего меню, чтобы объединить вашу ветвь с основной
  • Напишите детальный комментарий к запросу на скачивание и кликните “Create Pull Request”.

На изображении ниже “лес” ветвей был выбран для объединения в “основную” ветвь:

Теперь вы должны увидеть запрос на скачивание (пример изображения ниже):

  • Изучите вкладку “Files changed” (измененные файлы), чтобы увидеть, как изменится “основная” ветвь, если ветви были объединены.
  • Справа вы можете запросить обзор у членов вашей команды, отметив их Github ID. Если хотите, вы можете задать настройки репозитория, чтобы запросить утверждающего человека обзор, чтобы присоединить к основной ветви.
  • Как только запрос на скачивание одобрен, кнопка “Merge pull request” (присоединить запрос на скачивание) станет активной. Кликните на нее.
  • После завершения удалите вашу ветвь, как объясняется ниже.

Разрешение конфликтов

Если два человека модифицировали одну и ту же строку одновременно, возникает конфликт объединения. Опять же, Git отказывается принимать решение о том, какую версию сохранить, ео помогает вам найти конфликт. НЕ ПАНИКУЙТЕ. В большем количестве случаев его легко решить.

Например, в Github:

После объединения возникшего конфликта, откройте файл в любимом редакторе. Конфликт будет указан серией знаков:

Текст между <<<<<<< HEAD и ======= идет из вашего локального репозитория, а текст между ======= и >>>>>>> - из другой ветви (которая может быть исходной, мастер или любой выбранной вами ветвью).

Вам нужно решить, какую версию кода вы предпочитаете (или даже записать третью, включая изменения с обеих сторон, если необходимо), удалите все остальное и удалите все отметки, добавленные Git (<<<<<<< HEAD, =======, >>>>>>> origin/master/your_branch_name).

Затем сохраните файл, подготовьте и сделайте коммит: это коммит, который делает объединенные версии “официальными”. Не забудьте их потом выгрузить.

Чем чаще вы и другие совместно работающие люди скачиваете и выгружаете, тем меньше будет конфликт.

Примечание: Если вам удобно пользоваться консолью, есть более продвинутые опции слияния (например, игнорирование пустого пространства, приоритетность одного из авторов и т.п.).

Удаление вашей ветви

Как только ветвь объединена в мастер файл и больше не нужна, вы можете ее удалить.

46.10.0.1 Github + Rstudio

Перейдите в репозиторий на Github и нажмите кнопку для просмотра всех ветвей (рядом с выпадающим меню выбора ветвей). Теперь найдите свою ветку и нажмите на значок корзины рядом с ней. Более подробно об удалении ветви см. тут.

Убедитесь, что вы также удалили ветвь локально на своем компьютере. Это не будет сделано автоматически.

  • Из RStudio убедитесь, что вы находитесь в основной ветви
  • переключитесь на печать команд Git в терминале RStudio (“Terminal” - вкладка рядом с консолью R), и напечатайте: git branch -d branch_name, где “branch_name” - это имя ветви, которую нужно удалить
  • Обновите вашу вкладку Git и ветвь должна исчезнуть

46.10.0.2 В Github Desktop

Просто выделите ветвь, которую вы хотите удалить, и зайдите в меню Branch > Delete.

Разветвлечнеие

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

В Github кликните на кнопку “Fork”:

Это клонирует оригинальный репозиторий, но в вашем профиле. Теперь есть две версии репозитория на Github: оригинальная, которую вы не можете менять, и клонированная версия в вашем профиле.

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

Как только вы удовлетворены результатом, вы можете создать запрос на скачивание с Github или Github Desktop, чтобы начать разговор с владельцами/сопровождающими оригинального репозитория.

Что если вам нужны более свежие коммиты с официального репозитория?

Представьте, что кто-то внесет критические модификации в официальный репозиторий, который вы хотите включить в свою клонированную версию. Возможно синхронизировать ваше разветвление с официальным репозиторием. Это требует использования терминала, но это не слишком сложно. В основном, вам нужно запомнить, что: - upstream = официальный репозиторий, который вы не могли модифицировать - origin = ваша версия репозитория в вашем профиле Github

Вы можете прочитать этот самоучитель или выоплнить следующее:

Во-первых, напечатайте в своем терминале Git (внутри вашего репозитория):

git remote -v

Если вы еще не провели конфигурацию upstream-репозитория, вы должны увидеть две строки, начиная с origin. Они показывают удаленный репозиторий, который выполняет fetch и push. Помните, что origin - привычное имя вашей версии репозитория на Github. Например:

Теперь добавьте новый удаленный репозиторий:

git remote add upstream https://github.com/appliedepi/epirhandbook_eng.git

Здесь адрес - это адрес, который генерирует Github, когда вы клонируете репозиторий (см. раздел клонирование).Теперь у вас будет 4 удаленных указателя:

Теперь, когда готова настройка, когда вы хотите получить изменения из репозитория оригинала (upstream), вам нужно только зайти (checkout) в ветвь, которую вы хотите обновить, и напечатать:

git fetch upstream # получить новые коммиты из удаленного репозитория
git checkout the_branch_you_want_to_update
git merge upstream/the_branch_you_want_to_update  # объединение ветви upstream с вашей ветвью
git push # обновление вашей собственной версии удаленного репозитория

Если есть конфликты, вам нужно будет их решить, как объяснялось в разделе Устранение конфликтов.

Резюме: разветвление - клонирование, но на стороне сервера Github. Остальные действия типичны для действий при совместной работе над проектом (клонирование, выгрузка, скачивание, коммит, объединение, подача запросов на скачивание…).

Примечание: хотя разветвление - концепция, а не команда Git, оно также существует на других веб-хостах, например Bitbucket.

46.11 Что мы узнали

Мы узнали, как:

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

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

Однако знайте, что если вам нужно будет пойти дальше, Git предлагает больше возможностей для упрощения историй коммитов, откатов одного или нескольких коммитов, выбора коммитов и т.п. Что-то может звучать как волшебство, но когда вы узнали основы, потом будет легче продолжать работу.

Обратите внимание, что хотя панели Git в Rstudio и Github Desktop хороши для начинающих/ повседневного использования в нашей работе, они не предлагают интерфейса для промежуточных/продвинутых функций Git. Некоторые более полные интерфейсы позволяют вам делать больше с функционалом “навести и кликнуть” (как правило за счет более сложного макета).

Помните, что поскольку вы можете использовать любой инструмент в любой момент для отслеживания своего репозитория, вы можете легко установить интерфейс, чтобы его попробовать, либо чтобы выполнить менее частые сложные задачи, при этом предпочитая более простой интерфейс все остальное время (например, использовать Github Desktop большую часть времени и переключаться на SourceTree или Gitbash для конкретных задач).

46.12 Команды Git

Рекомендуемое обучение

Чтобы узнать команды Git в интерактивном самоучителе, см. этот сайт.

Где вводить команды

Вы вводите команды в оболочке Git.

Вариант 1 Вы можете открыть новый терминал в RStudio. Это вкладка рядом с консолью R. Если вы не можете напечатать текст в ней, кликните на выпадающее меню ниже “Terminal” и выберите “New terminal” (новый терминал). Напечатайте команды в мигающем пространстве перед знаком доллара “$”.

Вариант 2 Вы можете также открыть оболочку (терминал для ввода команд), кликнув синюю иконку с “шестеренками” во вкладке Git (рядом с рабочей средой RStudio). Выберите “Shell” (оболочка) из выпадающего меню. Откроется новое окно, где вы можете напечатать команды после знака доллара “$”.

Вариант 3 Правой кнопкой мыши кликните “Git Bash here”, что открое тот же тип терминала, либо откройте Git Bash из вашего списка приложений. Дополнительная информация о Git Bash, удобная для новичков, о том, как найти его и некоторых командах, которые вам понадобятся.

Примеры команд

Ниже мы представляем несколько часто используемых команд git. Когда вы их используете, помните, какая ветвь активна (взята), так как это изменит действие!

В командах ниже, представляет собой имя ветви. представляет собой хэш ID для конкретного коммит. представляет число. Не печатайте символы < или >.

Команда Git Действие
git branch <name> Создать новую ветвь с именем <имя>
git checkout <name> Переключить текущую ветвь на <имя>
git checkout -b <name> Краткая команда для создания новой ветви и переключения на нее
git status См. неотслеженные изменения
git add <file> Подготовить файл к коммит
git commit -m <message> Коммит подготовленных изменений в текущей ветви с сообщением
git fetch Получить коммиты из удаленного репозитория
git pull Скачать коммиты из удаленного репозитория в текущую ветвь
git push Выгрузить локальные коммиты в удаленную директорию
git switch Альтернатива для git checkout, которая вводится в Git
git merge <name> Слияние ветви <имя> в текущую ветвь
git rebase <name> Приложить коммиты из текущей ветви к ветви <имя>

46.13 Ресурсы

Большая часть информации для данной страницы была всзята с этого веб-сайта “Happy Git with R”, созданного Дженни Браян. Там есть очень полезный раздел, который поможет найти и устранить частые ошибки в Git и R.

Документация и руководство по началу работы с Github.com.

RStudio шпаргалка “IDE”, которая включает советы по Git в RStudio.

https://ohi-science.org/news/github-going-back-in-time

Команды Git для начинающих

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

https://www.freecodecamp.org/news/an-introduction-to-git-for-absolute-beginners-86fa1d32ff71/: хорошо подходит для изучения основ отслеживания изменений в одной папке на вашем компьютере.

Хорошая схема, чтобы понять ветви: https://speakerdeck.com/alicebartlett/git-for-humans

Самоучители по базовым и продвинутым темам

https://tutorialzine.com/2016/06/learn-git-in-30-minutes

https://dzone.com/articles/git-tutorial-commands-and-operations-in-git https://swcarpentry.github.io/git-novice/ (short course) https://rsjakob.gitbooks.io/git/content/chapter1.html

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