Version control setup for a tutorial

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 hi

Answer 1

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.

Answer 2

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 3

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 4

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.