Version control setup for a tutorial - version-control

Question

I'm trying to set up version control for a programming-related tutorial. It's proving problematic because there are two different kinds of history:
There's the history of the project being built by the tutorial, which is available for each chapter and is what the reader will see. If I never planned to change already-written chapters of the tutorial again, I could just store each chapter as a tag in the history of the project.
Then there's also the history of the tutorial itself (not only the text, but my working on the pretend history of the project). If I find a bug I need to go back and fix in chapter 1, adding a new commit to the end doesn't work because I want to change how the project "appeared" at that stage, i.e. insert a commit in the project history and move the chapter's tag forward.
So far I've thought about a few possibilities- using git branches where each chapter is a branch that gets rebased to the front of the previous chapter whenever I make a change, a mercurial patch queue that I insert patches into, or structuring the tutorial around a set of modules that I could put in subrepositories.
I thought I'd ask if anyone has experience with this kind of thing and what solutions worked and didn't.

Answer 1

Rather than rewriting the history of the all project because of a late fix to an early chapter, I would rather isolate each chapter in its own branch, have each HEAD representing the current state for each chapter.
Assembling the all tutorial is then more a release management issue (deploying your tutorial by extracting the relevant informations from the Git Repo).
You can then develop your tutorial to achieve something similar to git immersion.
(Note: If this was more an ebook you were after, then git-scribe would have been a more interesting way to version it.)
The OP rusky adds in the comments:
I'm trying to version the sample code for the chapters, where each chapter's code is based on the previous chapter's code
That means any bugfix you add needs to be reported to the other branches representing the other chapters, in which case see:
In Git, how do you apply a commit of bug fix to the other newer branches? (avoiding cherry-picking, which is generally a bad idea)
using a topic branch
rebase --onto solution

Answer 2

git rebase --interactive is probably the most straightforward solution here. That will let you choose a specific commit to edit, then reapply all the subsequent commits on top of it. Shouldn't be much more difficult than a regular merge, depending on how extensive your change is, of course. Check out the part of the git rebase man page on splitting commits. That will let you keep your original version for historical reasons, then add a new commit just after it in the history where you can move your tag.

Answer 3

The great thing about CLI-based version control is you can use shell scripts to build up tutorial examples, something like:
#!/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. It lets you build up a new repo from scratch to whatever point you like, and mistakes in the middle are easy to fix because you start from a blank slate every time. You can put the shell script itself under version control, or just comment out parts you don't need for different examples.

Answer 4

This is what tags are for. Tag your "snapshot" points, and go from there. If you need to go back and change something, do so and update the tag. And if you don't want people to see the in-between stages, simply create a second repository and incrementally check in your commits one tag at a time.