I feel like it might be sensible to provide e.g. a flag in git_checkout that enables the guessing heuristic.

Instead of a flag on checkout, I think a new API might be useful for callers to get the annotated commit from a "refish"? (Is there a better name than that?)

I think I'd stash this kind of function under branch, eg. git_branch_create_tracking (which I have some dead code for somewhere), and then let the checkout/switch part use that ? Because AFAIU there's no need to touch the working copy to create a tracking branch (says the guy who just read about locally-tracking branches 🙄) ?

annotated commit from a "refish"

I'm tempted to say that annotated commit actually are libgit2's "refish" — at least that's how the API felt when I needed to use merges/fetches/etc. Maybe I'm missing something though ?

I'm torn between both approaches. I honestly never quite got what annotated commits are about, but I guess describing them as "refish" which remembers where the actual commit was resolved from is probably kinda close. I can't quite imagine how branch creation would look like if we were to use annotated commits for this case, so on first sight git_branch_create_tracking sounds more obvious to me. Might just be me though for not having seen the approach @ethomson has in mind.

Anyway, can we merge this? Any future additions to the API can lift code out of the examples as required.

I didn't as well, until I wrote this example, and was enlightened about "how to convert refishs" in GitX. If that helps, this one is also a likely candidate for code-lifting.