Примітки для викладача

Використання програмного інструменту для обробки версій файлів вашого проєкту дозволяє зосередитися на більш цікавих/інноваційних аспектах вашого проєкту.

  • Переваги контролю версій
    • Його легко встановити
    • Кожна копія репозиторію Git є повною резервною копією проєкту та його історії
    • Кілька простих для запам’ятовування команд - це все, що потрібно для більшості повсякденних завдань з контролю версій
    • Послуга хостингу від GitHub надає вебплатформу для спільної роботи
  • Два основних поняття
    • commit: збережений набір змін у файлах вашого проєкту
    • repository: історія всіх комітів вашого проєкту
  • Навіщо використовувати GitHub?
    • Нема потреби в сервері: легко налаштувати
    • Численна спільнота GitHub: ваші колеги, напевно, вже там

Загалом

Контроль версій може бути найважливішою темою, яку ми викладаємо, але Git, безумовно, є найскладнішим інструментом. Однак, GitHub наразі домінує у сфері репозиторіїв відкритого програмного забезпечення, що робить час і зусилля для вивчення основ користування Git виправданими та цінними.

Через ці складнощі, ми не вчимо початківців багатьом цікавим темам, таким як гілки, хеші та об’єкти комітів.

Замість цього ми намагаємося переконати їх у тому, що контроль версій корисний для дослідників, які працюють в командах чи самостійно, бо це

  • ліпший спосіб “скасувати” зміни,
  • ліпший спосіб для співпраці, ніж розсилка файлів у різних напрямках, та
  • ліпший спосіб поділитися своїм кодом та іншими науковими роботами зі світом.

Нотатки щодо викладання

  • Ви можете “розділити” ваш термінал так, щоб останні команди залишалися в полі зору за допомогою цього скрипту.

  • Переконайтеся, що мережа працює до початку цього уроку.

  • Малюнки особливо корисні у цьому уроці: якщо у вас є дошка, користуйтеся нею!

  • Контроль версій, зазвичай, не перша тема, яка розглядається на семінарі, тому заохочуйте учнів створити обліковий запис GitHub заздалегідь, наприклад після попередньої сесії. Нагадайте слухачам, що ім`я користувача та адреса електронної пошти, яку вони використовують для GitHub (та налаштовують під час конфігурації Git), за замовчуванням будуть наявні для загального перегляду. Однак є багато причин, чому слухач може віддати перевагу зберіганню конфіденційності своєї особистої інформації, для чого GitHub надає наступні ресурси.

  • Якщо деякі слухачі використовують Windows, неминуче виникнуть проблеми з обєднанням файлів із різними закінченнями рядків. (Навіть якщо всі слухачі використовують Linux або macOS, різні редактори можуть автоматично додавати або не додавати новий рядок до останнього рядка файлу.) Знайдіть момент, щоб пояснити ці питання, оскільки слухачі майже напевно зіткнуться з ними знову. Якщо учні стикаються з проблемами закінчення рядків, GitHub має корисну [сторінку][github-line-endings]. Зокрема, [розділ про оновлення репозиторію][github-line-endings-refresh] може бути корисним, якщо учням потрібно змінити налаштуванняcore.autocrlf` після того, як вже зробили один або кілька комітів.

  • Ми не використовуємо Git GUI в цих нотатках, бо не знайшли графічний інтерфейс, який плавно встановлюється та надійно працює у трьох основних операційних системах. Крім того, нам треба, щоб учні розуміли основні команди, які виконуються. Проте, інструкторам треба продемонструвати графічний інтерфейс на своєму комп’ютері в деякий момент цього уроку та вказати учням на цю сторінку.

  • Інструктори повинні продемонструвати слухачам графічні інструменти для аналізу і злиття змін, такі як DiffMerge.

  • При необхідності поясніть, що ми перш за все навчаємо використовувати Git, а не CVS, Subversion, або Mercurial насамперед через зростання популярності GitHub. CVS та Subversion тепер вважаються застарілими системами, а Mercurial наразі не так широко використовується у наукових галузях.

  • Додаткові ресурси:

    • git-it — це навчальна програма з Git, яка працює у терміналі, а git-it-electron — це її наступна версія, яка має графічний інтерфейс користувача.
    • Code School пропонує безкоштовний інтерактивний курс Try Git.
    • для викладачів корисною довідковою літературою є Git parable.

Автоматизований контроль версії

  • Запитайте, “Хто використовує функцію скасування (undo) у своєму редакторі?” Всі скажуть: “Я”. Скасування - це найпростіша форма контролю версій.

  • Надайте слухачам п’ятихвилинний огляд того, що для них може зробити система контролю версій, перш ніж перейти до практичних “повторюйте за мною” вправ. Більшість з них натрапили на труднощі зі співавторством, надсилаючи файли електронною поштою. Дехто буде знайом із такою ситуацією: приїжджаєш до офісу лише для того, щоб зрозуміти, що USB-ключ із роботою минулої ночі все ще вдома. Інструктори також можуть жартувати про каталоги з назвами на кшталт “остаточна версія”, “переглянута остаточна версія”, “остаточна версія з трьома виправленнями”, “дійсно остаточна версія”, та “це вже дійсно має бути остання версія”, щоб заохочувати контроль версій як ліпший спосіб для співпраці та резервного копіювання роботи.

Налаштування Git

  • Ми радимо інструкторам та слухачам використовувати nano як текстовий редактор для цих уроків, тому що

    • він працює у всіх трьох основних операційних системах
    • він працює всередині терміналу (перемикання вікон може заплутати учнів), та
    • він містить у нижній частині вікна довідку з клавіатурними скороченнями.

    Будь ласка, нагадайте слухачам під час налаштування, що вони можуть (і навіть мають) використовувати інший текстовий редактор, якщо вони вже з ним знайомі.

  • Під час налаштування Git чітко вказуйте, що слухачі мають вводити: зазвичай вони редагують деталі викладача (наприклад, електронну пошту). Зрештою, перевірте це за допомогою git config --list.

  • При встановленні типової назви гілки, якщо слухачі мають версію Git старішу за 2.28, назву гілки для уроку можна змінити за замовчуванням за допомогою ‘git branch -M main’ - коли в репозиторії є коміти, або ‘git checkout -b main’ - коли комітів немає/репозиторій повністю порожній.

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

  • Коли ви вводите ‘git status’, користувачі Mac можуть побачити файл ‘.DS_Store’, який відображується як не відстежуваний. Це файл, який Mac OS створює в кожному каталозі.

  • Завдання “Місця для створення репозиторіїв” намагається посилити ідею, що каталог .git містить весь репозиторій Git і видалення цього каталогу скасовує git init. Це також дає слухачеві можливість виправити поширену помилку, пов’язану з додаванням небажаних каталогів (наприклад, Робочий стіл) до контролю версій.

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

    BASH 

    $ mv .git temp_git
$ rm -rf  temp_git

    Завдання натякає на те, що створення репозиторію Git всередині іншого є поганою ідеєю. Для додаткової дискусії на цю тему, будь ласка, дивіться це питання.

Відстеження змін

  • Важливо, щоб слухачі самостійно зробили повний цикл коміту (внесли зміни та виконали git diff, git add, та git commit). Завдання “репозиторій bio” допоможе з цим.

  • Це слушний момент, щоб показати diff за допомогою графічного інструмента. Якщо ви пропустите це через брак часу, пізніше продемонструйте його лише у GitHub.

  • Одна річ, яка може викликати плутанину - це відновлення старих версій. Якщо замість команди $ git checkout f22b25e mars.txt, хтось введе $ git checkout f22b25e, то вони опиняться у стані “detached HEAD”, що призведе до непорозуміння. Після цього можна продовжувати робити коміти, але такі команди, як git push origin main вже не надаватимуть зрозумілих результатів. Це також створює враження, що коміти можуть бути втрачені. Щоб “повторно прикріпити” HEAD, використовуйте git checkout main.

  • Це слушний момент, щоб показати журнал у графічному інтерфейсі Git. Якщо ви пропустите це через брак часу, пізніше продемонструйте його лише у GitHub.

Ігнорування файлів

Просто пам’ятайте, що ви можете використовувати шаблони та регулярні вирази, щоб ігнорувати певний набір файлів в .gitignore.

Віддалені репозиторії у GitHub

  • Поясніть, що Git і GitHub - це не одне і те ж саме: Git - це інструмент контролю версій з відкритим кодом, GitHub - це компанія, яка розміщує Git репозиторії в Інтернеті та надає вебінтерфейс для взаємодії з репозиторіями, які вони розміщують.

  • Дуже корисно намалювати діаграму, що показує різні залучені репозиторії.

  • При надсиланні змін до віддаленого репозиторію, вихідні дані з Git можуть дещо відрізнятися в залежності від того, що виконують слухачі. Урок відображує результат з git, якщо слухач виконує git push origin main. Однак, деякі слухачі можуть використовувати синтаксис git push -u origin main, що може запропонувати GitHub, для відправлення на наявний віддалений репозиторій. Слухачі, які використовують синтаксис від GitHub, git push -u origin main, матимуть дещо інший результат, в тому числі рядок Branch main set up to track remote branch main from origin by rebasing.

Співпраця

  • Вирішіть заздалегідь, чи всі учні працюватимуть в одному спільному репозиторії, або у парах (або інших невеликих групах) в окремих репозиторіях. Перший варіант легше налаштувати; а другий працює більш плавно.

  • Рольова гра між двома інструкторами може бути ефективним методом навчання співпраці та розв’язанню конфліктів. Один інструктор може грати роль власника репозиторію, а другий інструктор може грати роль співавтора. Якщо є можливість, спробуйте використовувати два проєктори, щоб було видно компʼютерні екрани обох інструкторів. Це чітко покаже слухачам хто що робить.

  • Також ефективно під час цього уроку поєднувати учнів у пари та призначати їм ролі власника та співавтора. У цьому сценарії, завдання можуть містити прохання до співавтора внести зміни, зробити коміт і відправити його до віддаленого репозиторію, так що власник може потім його отримати, і навпаки. Рольова гра між викладачами може стати досить “драматичною” під час частини уроку, присвяченої розв’язанню конфліктів, особливо якщо викладачі вирішать додати трохи гумору до уроку.

  • Якщо у вас немає двох проєкторів, подібний ефект можна досягти за допомогою двох інструкторів. Кожен інструктор розповідає про свою частину на власному компʼютері, а потім передає шнур проєктора іншому коли настає його черга. Кожне перемикання проєктора займає менше ніж 10 секунд, тому це не порушить хід уроку. Для покращення гри корисно дати кожному з інструкторів кольорові капелюхи або наліпки на лоба.

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

    BASH 

    $ git clone https://github.com/vlad/planets.git planets-at-work

  • Під час додавання віддаленого репозиторію, поширеною помилкою є неправильне введення псевдоніму або URL-адреси, що може завадити їм виконати git push. Ви можете уникнути цього за допомогою виконання git remote -v і ретельної перевірки результату.

    • Щоб виправити помилковий псевдонім, скористайтеся командою git remote rename <old> <new>.
    • Щоб виправити помилковий URL, ви можете виконати git remote set-url <alias> <newurl>.

  • Перш ніж клонувати репозиторій, переконайтеся, що ніхто зі слухачів не знаходиться всередині іншого репозиторію. Найкращий спосіб досягти цього - перейти на робочий стіл перед клонуванням: cd && cd Desktop.

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

    BASH 

    $ git clone https://github.com/vlad/planets.git vlad-planet

  • Найпоширенішою помилкою є те, що слухачі відправляють свої зміни (git push) перед тим, як отримати інші зміни з віддаленого репозиторію (git pull). Якщо вони виконують pull після push, може виникнути конфлікт.

  • Іноді можуть виникнути дивні конфлікти. Зберігайте спокій: конфлікти розглядаються у наступному епізоді.

  • Слухачі іноді матимуть дещо інші результати від команд git push та git pull, залежно від версії git і того, чи використовується опція -u (upstream).

Конфлікти

  • Очікуйте, що учні зроблять помилки. Очікуйте, що ви можете зробити помилки. Це відбувається тому, що урок триває вже достатньо довго і всі втомилися.

  • Якщо ви єдиний інструктор, найкращий спосіб створити конфлікт є наступним:

    • Клонуйте свій репозиторій в інший каталог, вдаючи, що це ваш комп’ютер на роботі: git clone https://github.com/alflin/recipes.git recipes-at-work.
    • В “офісі” внесіть зміни, збережіть їх у коміті та відправляєте їх до GitHub.
    • Потім, без отримання останніх змін, внесіть свої власні у репозиторій на вашому компʼютері, збережіть їх у коміті, та спробуйте надіслати їх до GitHub.
    • Тепер введіть git pull та покажіть як виглядає конфлікт.

  • Учні зазвичай забувають git add файл після виправлення конфлікту та просто (намагаються) зробити коміт. Ви можете це продіагностувати за допомогою git status.

  • Памʼятайте, що можливо скасувати зміни в одній з двох версій, що зливаються:

    • скасувати зміни у віддаленому файлі, git checkout --ours conflicted_file.txt
    • скасувати зміни у локальному файлі, git checkout --theirs conflicted_file.txt

    Після цього вам все одно потрібно зробити git add та git commit. Це особливо має відношення до роботи з бінарними файлами.

  • Майте на увазі, що в залежності від версії Git, яку ви використовуєте, результати для git push та git pull можуть дещо відрізнятися.

Відкрита наука

Ліцензування

Ми розповідаємо про ліцензування, тому що завжди виникатимуть питання про права володіння: хто володіє чим, або що можна використовувати. Ці питання з’являються як тільки ми починаємо говорити про використання публічних послуг як GitHub для зберігання файлів. Крім того, обговорення дає учням можливість перевести подих після тривалого навантаження.

Ліцензії Creative Commons рекомендуються для багатьох типів робіт (зокрема для програмної документації та зображень, які використовуються в програмному забезпеченні), але не для програмного забезпечення. Creative Commons рекомендує обирати одну зі спеціалізованих ліцензій для програмного забезпечення.

Цитування

Хостинг

Спільним занепокоєнням серед слухачів є те, що їхня робота буде загальнодоступною на GitHub. Хоча ми заохочуємо відкриту науку, іноді приватні репозиторії є єдиним варіантом. Завжди цікаво згадати варіанти розміщення приватних репозиторіїв.