Skip to content

Latest commit

 

History

History
264 lines (201 loc) · 14 KB

github.md

File metadata and controls

264 lines (201 loc) · 14 KB
Raw

Как писать диссертацию на GitHub?

Hint

При использовании Git может оказаться полезным добавить нужные для пакета gitinfo2 файлы в локальную копию .git/hooks, тогда в режиме черновика на каждой странице диссертации будет указываться используемая ревизия документа (короткий хэш коммита) и дата его внесения.

Без обновления шаблона

Описанную ниже схему можно использовать для того, чтобы писать свою диссертацию на GitHub используя шаблон Russian-Phd-LaTeX-Dissertation-Template

  1. Создаём учётную запись на GitHub.

  2. Логинимся, жмём значок Fork на главной странице шаблона. После этого шаблон появится в списке репозиториев уже вашей учётной записи.

  3. Открываем свою копию шаблона. Жмём кнопку Branch:master, в поле «Find or create a branch» пишем имя для ветки репозитория под свой диссер. У меня (@kostyfisik) это «disser-Ladutenko». Если после нажатия на кнопку в поле ввода вы видите надпись «Filter branches/tags» — вы в чужой копии репозитория.

  4. Дальше можно клонировать шаблон к себе на компьютер. Делать это надо из СВОЕЙ копии шаблона!

  5. Пишем диссер в своей ветке, радуемся возможностям системы контроля версии, например можно утром посмотреть, а что именно ты менял по тексту вчера в 3 часа ночи…

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

Продвинутый неленивый научник сделает вам pull request с предлагаемыми изменениями. Хорошей идей может оказаться использовать инструменты для code review и collaboration, существующие на GitHub. Перед тем как вносить изменения уже в ветку со своими изменениями — создаёте ещё одну ветку, а потом из неё делаете pull request в свою основную ветку дисера. Ссылку на изменения в PR можно послать научнику, а он может прямо на сайте добавлять комментарии именно по предлагаемым изменениям (т.е. он их сможет просматривать инкрементально, а не по всему дисеру сразу). Можно заводить личные issue (или их может добавлять научник), вроде «добавить картинку XXX», «изменить описание эффекта YYY» и т.д. Оптимизируйте ваш рабочий процесс, сделайте его максимально эффективным!

С обновлением

Остальные инструкции выполняются из командной строки в Linux, а для Winodows\Mac есть программы для работы с git… в которых тоже можно выполнять указанные ниже команды! Нужны они для того, чтобы улучшения в основном шаблоне можно было наложить поверх уже начатого дисера.

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

git remote add upstream https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template

  1. Теперь в любой момент можно обновить свою локальную копию и свою копию на сайте GitHub следующим набором команд.

Переключаемся в master ветку: git checkout master

Синхронизируем локальную копию с своей копией на сайте: git pull

Получаем актуальные обновления: git fetch upstream

Смотрим что поменялось: git diff upstream/master

Сливаем изменения в свою локальную копию: git merge upstream/master

Отправляем их в свою копию на сайте: git push

  1. Не сложно подтянуть обновления уже непосредственно в свой диссер. Для этого (подставлено имя моей ветки диссера):

git checkout disser-Ladutenko

по желанию: git diff master

git merge master

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

Updating 22ca047..112b54a
Fast-forward
 Dissertation/disstyles.tex                |  16 +++++++++-
 README.md                                 |   8 +++--
 Bibliography.md => Readme/Bibliography.md |   0
 Installation.md => Readme/Installation.md |   6 ++--
 Links.md => Readme/Links.md               |   0
 Readme/github.md                          | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Synopsis/synstyles.tex                    |  19 ++++++++---
 Synopsis/title.tex                        |  77 ++++++++++++++++++++++-----------------------
 Synopsis/userstyles.tex                   |   1 +
 biblio/biblatex.tex                       |   8 ++---
 common/data.tex                           |  18 ++++++-----
 common/styles.tex                         |   6 ----
 synopsis.tex                              |  33 ++++++++++++++++++--
 13 files changed, 284 insertions(+), 71 deletions(-)
 rename Bibliography.md => Readme/Bibliography.md (100%)
 rename Installation.md => Readme/Installation.md (96%)
 rename Links.md => Readme/Links.md (100%)
 create mode 100644 Readme/github.md
  1. В противном случае может потребоваться ручное разрешение конфликтов. Например,
$ git merge master
Auto-merging dissertation.tex
Auto-merging common/styles.tex
CONFLICT (content): Merge conflict in common/styles.tex
Auto-merging common/packages.tex
CONFLICT (content): Merge conflict in common/packages.tex
Auto-merging Dissertation/userstyles.tex
Auto-merging Dissertation/userpackages.tex
Auto-merging Dissertation/part3.tex
CONFLICT (content): Merge conflict in Dissertation/part3.tex
Auto-merging Dissertation/part2.tex
CONFLICT (content): Merge conflict in Dissertation/part2.tex
Auto-merging Dissertation/appendix.tex
CONFLICT (content): Merge conflict in Dissertation/appendix.tex
Automatic merge failed; fix conflicts and then commit the result.

Тогда надо каждый файл с конфликтом открыть и исправить конфликт вручную.

Для файлов partX.tex это, как правило, означает, что надо удалить строчку

<<<<<<< HEAD

в начале файла, найти строчку

=======

и удалить от неё до строчки

>>>>>>> master

Чаще всего хочется оставить HEAD, но могут быть варианты. Например:

<<<<<<< HEAD
%%% Макет страницы %%%
% Выставляем значения полей (ГОСТ 7.0.11-2011, 5.3.7)
\geometry{a4paper,top=2cm,bottom=2cm,left=2.5cm,right=1cm}

=======
>>>>>>> master

Описание к геометрии уехало в другой файл, так что его удаляем, а от master останется пустое место.

Ещё пример:

<<<<<<< HEAD
%%% Интервалы %%%
\usepackage[onehalfspacing]{setspace} % Опция запуска пакета правит не только интервалы в обычном тексте, но и формульные
\usepackage{needspace}

%%% Разрывы страниц %%%
% \needspace{2\baselineskip} располагает две последующие строчки на
% одной странице. Тут используется, чтобы слово "задачи" и "положения"
% оказались на одной странице со списком из задач и положений
%\usepackage{needspace}
\makeatletter
\newcommand\mynobreakpar{\par\nobreak\@afterheading}
\makeatother

=======
>>>>>>> master

Объявления \usepackage переехали в другой файл, их тут удаляем, блок про разрыв страниц оставляем. Служебные

<<<<<<< HEAD
=======
>>>>>>> master

разумеется, удаляем.

После того как все конфликты разрешены — не забудьте сделать финальный коммит, который я обычно называю merge.

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

Если что-то пошло не так

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

Синхронизация с upstream (для продвинутых пользователей)

Шаблон время от времени обновляется, и может возникнуть желание добавить полезные изменения к себе в работу. Однако делать это при помощи merge может быть проблематично. Для таких случаев удобно использовать команду git rebase.

Рассмотрим ситуацию -- вы начали писать свою работу после коммита номер 3 в ветке master. После этого шаблон был обновлён в ветке upstream. Эта ситуация проиллюстрирована на рисунке ниже.

+--------+     +--------+     +--------+     +--------+     +--------+
|commit 1+----->commit 2+----->commit 3+--+-->commit 4+----->commit 5|   upstream
+--------+     +--------+     +--------+  |  +--------+     +--------+
                                          |
                                          |
                                          |  +--------+     +--------+
                                          +-->commit 6+----->commit 7|   master*
                                             +--------+     +--------+

Для merge в данном случае наверняка понадобится разрешать множество конфликтов. git предоставляет более лёгкий способ синхронизации изменений -- rebase.

Для слияния веток введите команду:

git rebase upstream

После этого git применит Ваши изменения начиная с последнего коммита ветки upstream. Результат этой операции будет выглядеть так:

                                                             upstream
+--------+     +--------+     +--------+     +--------+     +--------+     +---------+     +---------+
|commit 1+----->commit 2+----->commit 3+----->commit 4+----->commit 5+----->commit 6*+----->commit 7*|   master
+--------+     +--------+     +--------+     +--------+     +--------+     +---------+     +---------+

Такой подход вызовет минимальное количество конфликтов (если у веток только одно пересечение).

Минусом данного подхода является то, что hash всех коммитов ветки master будет изменён. Следствием этого будет то, что ссылки на эти коммиты в issue tracker будут сломаны, так что данный способ лучше не использовать при наличии ссылок на коммиты в issue tracker.

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

git push --force origin master

А при последующей синхронизации на другом компьютере надо будет использовать:

git fetch origin
git reset --hard origin/master