Git для соавтора курса: минимум

Эта инструкция — для тех, кто раньше не работал с Git. Её достаточно, чтобы писать свои лекции в общем репозитории и ничего не сломать. Как устроены файлы лекции и как их собирать, описано в quarto-guide.md.

Три понятия

  • Репозиторий — папка курса вместе со всей историей изменений. Главная копия лежит на GitHub: https://github.com/NeutrinoHit/numerical_methods.
  • Коммит — сохранённый снимок изменений с коротким описанием. Коммиты можно посмотреть и откатить, поэтому потерять работу трудно.
  • Ветка — отдельная линия коммитов. Ветка main — это то, что опубликовано на сайте. Вы работаете в своей ветке; в main её переносит Д. В. Наумов после просмотра.

Правило одно: вы никогда не пишете в main напрямую. Всё остальное можно исправить.

Один раз: установка и вход

  1. Установите Git:

    • macOS: в Терминале xcode-select --install;
    • Windows: https://git-scm.com/download/win (дальше используйте программу Git Bash);
    • Linux: sudo apt install git или аналог.

  2. Представьтесь Git (имя и почта попадут в коммиты):

    git config --global user.name "Кирилл Базаров"
git config --global user.email "ваша-почта@example.com"

  3. Заведите аккаунт на GitHub и сообщите логин Д. В. Наумову: он добавит вас в репозиторий.

  4. Установите GitHub CLI (https://cli.github.com/) и войдите:

    gh auth login

    Отвечайте: GitHub.com → HTTPS → Login with a web browser.

  5. Скачайте репозиторий в удобную папку:

    gh repo clone NeutrinoHit/numerical_methods
cd numerical_methods

Начать лекцию

Одна лекция — одна ветка. Имя ветки: lec/NN-slug, где NN — номер лекции в программе курса (страница слайдов, список «Лекции курса»), а slug — имя файла лекции, например lec/07-heat_equation.

git switch main
git pull
git switch -c lec/07-heat_equation

git switch -c создаёт ветку. Если ветка уже есть, вернуться в неё: git switch lec/07-heat_equation.

Рабочий цикл

Работайте только с файлами своей лекции (список — в quarto-guide.md, раздел «Файлы лекции»). Закончили кусок работы — сохраните его:

git status

показывает изменённые и новые файлы. Добавьте по имени только свои файлы:

git add ru/slides/planned/heat_equation.qmd ru/book/planned/heat_equation.qmd
git commit -m "Теплопроводность: явная схема и условие устойчивости"

Описание коммита — одна фраза о том, что изменилось. Коммитьте часто: маленький коммит легко посмотреть и легко откатить.

Отправьте ветку на GitHub (первый раз — с -u, дальше просто git push):

git push -u origin lec/07-heat_equation

Показать работу: pull request

Когда лекция (или её заметная часть) готова к просмотру:

gh pr create --base main --fill

или кнопка «Compare & pull request» на странице репозитория. Pull request — это просьба перенести ветку в main. Д. В. Наумов посмотрит изменения, оставит замечания и сам выполнит слияние. Исправления по замечаниям — обычные коммиты в ту же ветку и git push: pull request обновится сам.

Подтянуть свежий main

Если в main появилось новое (например, общие стили), перенесите это в свою ветку:

git switch main
git pull
git switch lec/07-heat_equation
git merge main

Если Git сообщает о конфликте и вы не уверены, что делать:

git merge --abort

— всё вернётся как было; напишите Д. В. Наумову.

Как отменить

Ситуация Команда
Испортил файл, хочу вернуть последнюю сохранённую версию git restore путь/к/файлу
Добавил в git add лишний файл git restore --staged путь/к/файлу
Опечатка в описании последнего коммита, ещё не отправленного git commit --amend -m "Новое описание"
Посмотреть историю git log --oneline
Что-то другое остановиться и спросить

Не делать

  • Не коммитить в main и не сливать ветки в main самому.
  • Не использовать git push --force, git reset --hard, git add . и git add -A.
  • Не коммитить результаты сборки (_site/, _book/, папки *_files/): они создаются заново при каждой сборке.
  • Не править общие файлы: _quarto.yml, index.qmd, shared/, чужие лекции. Если нужно изменить общее — напишите, это отдельная ветка.
  • Не хранить в репозитории пароли, ключи и чужие материалы без разрешения.