Настройка контроля версий для учебника

Question

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

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

Также есть история самого урока (не только текст, но и моя работа над притворной историей проекта). Если я найду ошибку, мне нужно вернуться и исправить ее в главе 1, добавление нового коммита до конца не работает, потому что я хочу изменить то, как проект «появился» на этом этапе, то есть вставить коммит в историю проекта. и переместите тег главы вперед.

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

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

Answer 1

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

Затем вы можете разработать учебник для достижения чего-то похожего на git immersion .

(Примечание: если бы это была книга, которую вы искали, то git-scribe был бы более интересным способом ее версии.)

---

OP rusky добавляет в комментариях:

Я пытаюсь создать версию кода для глав, где код каждой главы основан на коде предыдущей главы

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

• В Git, как применить исправление ошибки к другим более новым ветвям? (избегая выбора вишен, что, как правило, плохая идея)
• с использованием ветки темы
• rebase --onto решение

Answer 2

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

Answer 3

Самое замечательное в управлении версиями на основе CLI заключается в том, что вы можете использовать сценарии оболочки для создания учебных примеров, например:

#!/bin/bash
mkdir example_repo
cd example_repo
git init .
touch file1
git add file1
git commit -m "Added file 1"
git checkout -b branch2
echo "New line" > file1
git commit -am "Added new line to file 1"

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

Answer 4

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