Setting up version control for the tutorial

Question

I am trying to customize a version control for a programming tutorial. This proves the problem because there are two different stories:

There is the history of the project created by the manual, available for each chapter, and what the reader will see. If I never planned to change already written chapters of the textbook, I would simply save each chapter as a tag in the history of the project.

Then there is also the history of the textbook itself (not only the text, but also my work on the feigned history of the project). If I find a mistake, I need to go back and fix it in Chapter 1, adding a new commit will not work until the end, because I want to change how the project "appeared" at this stage, i.e. Paste the commit into the project history and move the chapter tag forward.

So far, I’ve been thinking of several possibilities using git branches, where each chapter is a branch that is reinstalled at the beginning of the previous chapter whenever I make changes, the mercury correction queue into which I insert the corrections, or structuring the tutorial around a set of modules, which I could place in subrepositories.

I thought I would ask if anyone had experience with this, and what solutions work, and not.

Answer 1

git rebase --interactive is probably the easiest solution here. This will allow you to select a specific commit for editing, and then reapply all subsequent commits on top of it. Of course, it should not be much more complicated than a regular merge, depending on how extensive your changes are. Check out the part of the git rebase man page when sharing commits. This will allow you to save the original version for historical reasons, and then add a new commit immediately after it to the history where you can move your tag.

Answer 2

Instead of rewriting the history of the entire project due to the late correction of the previous chapter, I would prefer to isolate each chapter in my branch, let each HEAD represent the current state for each chapter.
Assembling the entire tutorial is more of a release management problem (deploying the tutorial by extracting relevant information from Git Repo).

You can then design your tutorial to achieve something like git diving .

(Note: if it was more the book you used, then git-scribe would be a more interesting way to version it.)

---

OP rusky adds in the comments:

I am trying to execute a version of the example code for chapters, where each chapter code is based on the previous chapter code

This means that any addition of a patch must be reported to other branches representing other chapters, in which case see:

• In Git, how do you apply bug fixes to other newer branches? (avoiding picking cherries, which is usually bad)
• using topic thread
• rebase --onto solution

Answer 3

The great thing about CLI-based versioning is that you can use shell scripts to create sample tutorials, for example:

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

You get the idea. This allows you to create a new repo from scratch to any point you like, and errors in the middle are easy to fix because you start from scratch every time. You can put the shell script yourself under version control or just comment out the parts that you don't need for different examples.

Answer 4

For this you need tags. Mark your “snapshots” and from there. If you need to go back and change something, do it and update the tag. And if you do not want people to see the intermediate steps, just create a second repository and step-by-step check in your commits one tag at a time.