CVS migration section to the tutorial.

I think a section to discuss "I am used to doing 'cvs xxx' to solve this problem, how do I do that in GIT" would be a good idea. Here is an example to talk about "cvs annotate".

------------

CVS annotate.

The core GIT itself does not do "cvs annotate" equivalent, but it has something much nicer.

Let's step back a bit and think about the reason why you would want to do "cvs annotate a-file.c" to begin with.

	- Are you really interested in _all_ the lines in that file?

	- Are you interested in lines _only_ in that file and do not
          care if the file was created by renaming from a different
          file?

You would use "cvs annotate" on a file when you have trouble with a function (or even a single "if" statement in that function) that happens to be defined in the file, which does not do what you want it to do. And you would want to find out why it was written in that way, because you are about to modify it to suit your needs, and at the same time you do not want to break its current callers. For that, you want to find out why the original author did things that way in the original context. That's why you want "cvs annotate". So your answer to the first question _should_ be "no". You do not care about the whole file, only a segment of it.

Also, in the original context, the same statement might have appeared at first in a different file and later the file was renamed to "a-file.c". Or the entire program may have constructs similar to the "if" statement you are having trouble with in different places, that you are still not aware of. So your answer to the second question _should_ be "no" as well.

As an example, assuming that you have this piece code that you are interested in in the HEAD version:

	if (frotz) {
		nitfol();
	}

you would use git-rev-list and git-diff-tree like this:

	$ git-rev-list HEAD |
	  git-diff-tree --stdin -v -p -S'if (frotz) {
		nitfol();
	}'

We have already talked about the "--stdin" form of git-diff-tree command that reads the list of commits and compares each commit with its parents. What the -S flag and its argument does is called "pickaxe", a tool for software archaeologists. When "pickaxe" is used, git-diff-tree command outputs differences between two commits only if one tree has the specified string in a file and the corresponding file in the other tree does not. The above example looks for a commit that has the "if" statement in it in a file, but its parent commit does not have it in the same shape in the corresponding file (or the other way around, where the parent has it and the commit does not), and the differences between them are shown, along with the commit message (thanks to the -v flag). It does not show anything for commits that do not touch this "if" statement.

To make things more interesting, you can give the -C flag to git-diff-tree, like this:

	$ git-rev-list HEAD |
	  git-diff-tree --stdin -v -p -C -S'if (frotz) {
		nitfol();
	}'

When the -C flag is used, file renames and copies are followed. So if the "if" statement in question happens to be in "a-file.c" in the current HEAD commit, even if the file was originally called "o-file.c" and then renamed in an earlier commit, or if the file was created by copying an existing "o-file.c" in an earlier commit, you will not lose track. If the "if" statement did not change across such rename or copy, then the commit that does rename or copy would not show in the output, and if the "if" statement was modified while the file was still called "o-file.c", it would find the commit that changed the statement when it was in "o-file.c".

[ BTW, the current versions of "git-diff-tree -C" is not eager enough
  to find copies, and it will miss the fact that a-file.c was created
  by copying o-file.c unless o-file.c was somehow changed in the same
  commit.]

To make things even more interesting, you can use the --pickaxe-all flag in addition to the -S flag. This causes the differences from all the files contained in those two commits, not just the differences between the files that contain this changed "if" statement:

	$ git-rev-list HEAD |
	  git-diff-tree --stdin -v -p -C -S'if (frotz) {
		nitfol();
	}' --pickaxe-all