4

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.

rpjohnst
  • 1,612
  • 14
  • 21

4 Answers4

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:

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • I'm trying to version the sample code for the chapters, where each chapter's code is based on the previous chapter's code. – rpjohnst May 08 '11 at 02:36
  • @Rusky: the problem of reporting a bugfix to other branches has been addressed before: see the links I have added in my answer. – VonC May 08 '11 at 10:22
1

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.

Karl Bielefeldt
  • 47,314
  • 10
  • 60
  • 94
  • That's an interesting idea. I wonder how it would scale to lots of code, though- it would probably end up with a lot of heredocs or else some kind of cherry-picking from a "real" repository of the project. – rpjohnst May 08 '11 at 02:43
  • @Rusky, based on your comment I think I misunderstood your original intention. My answer was based on the subject of your tutorial being the use of version control itself, i.e. branching models and so forth, not sample code. – Karl Bielefeldt May 08 '11 at 06:32
  • I added a new answer now that I better understand your question. Decided against just editing this one because someone may find it useful in another circumstance. – Karl Bielefeldt May 08 '11 at 07:05
1

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.

Karl Bielefeldt
  • 47,314
  • 10
  • 60
  • 94
0

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.

Chris Eberle
  • 47,994
  • 12
  • 82
  • 119
  • I'm not sure I follow- if I tag the code as I want it to appear in chapter 1, add some more commits and then go back and add a new commit based on chapter 1, the later stuff won't have that fix unless I do something like rebasing or merging. – rpjohnst May 07 '11 at 22:34
  • That is correct. It won't be fun. You can cherry pick the commits (if you use git) to apply it to all of the later tags. – Chris Eberle May 07 '11 at 22:41