教程的版本控制设置

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 的版本控制的好处是您可以使用 shell 脚本来构建教程示例，例如：

#!/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"

您明白了。它可以让你从头开始构建一个新的存储库到你喜欢的任何点，并且中间的错误很容易修复，因为你每次都是从一张白纸开始。您可以将 shell 脚本本身置于版本控制之下，或者只是注释掉不同示例中不需要的部分。

Answer 4

这就是标签的用途。标记您的“快照”点，然后从那里开始。如果您需要返回并更改某些内容，请执行此操作并更新标签。如果您不希望人们看到中间的阶段，只需创建第二个存储库并一次增量地检查您的提交一个标签即可。