Yes, the reference parameter represents the in-odb history of the file. This effectively caches most of the work blame does, so that `git_blame_buffer` only has to do a single diff. 

The use case here is something like a text editor, where you may have modified the file in memory, but not saved it to the worktree or the index. So yeah, it goes straight to `HEAD` (or whatever you specified for `newest_commit`). 

You bring up a good point, though; should we have some way of "blaming" to the worktree or the index? That might be interesting and maybe even useful, and doing three diffs isn't that much more expensive than doing one. Maybe this behavior could be optional?

Regardless, I didn't get this across in the doc-comments, and that needs fixed.