Ahead / behind #65

We discussed in Slack but I'll open a real issue.

It would be great to get something like git2r::ahead_behind(), which wraps libgit2's git_graph_ahead_behind():

https://libgit2.org/libgit2/#HEAD/group/graph/git_graph_ahead_behind

Here's where it would drop in to an internal helper in usethis:

git_branch_compare <- function(branch = git_branch(), remref = NULL) {
  remref <- remref %||% git_branch_upstream(branch)
  gert::git_fetch(
    remote = remref_remote(remref),
    refspec = remref_branch(remref),
    repo = git_repo(),
    verbose = FALSE
  )
  # TODO: replace with something from gert
  out <- git2r::ahead_behind(
    git2r::revparse_single(repo = git2r_repo(), revision = branch),
    git2r::revparse_single(repo = git2r_repo(), revision = remref)
  )
  stats::setNames(as.list(out), nm = c("local_only", "remote_only"))
}

I have a few ideas for improvements on git2r::ahead_behind(). I'm not sure the name is very helpful and the return value is very spartan:

An integer vector of length 2 with number of commits that the upstream commit is ahead and behind the local commit

This is from libgit2's docs, explaining what ahead and behind are (I think they have a wording problem? maybe delete "from" here):

I think it would be great if the return value was a named list (not 2 integers), where the names refer clearly back to the argument names used to identify the 2 refs (commits) being compared. This makes downstream code more self-explanatory, i.e. you can do if (x$remote_only > 0) {...} instead of if if (x[2] > 0) {...}.

Name-wise, I find "compare" or "comparison" more evocative than ahead/behind. And I also like thinking of the return values as the number of commits that are unique to one ref, as opposed to the ahead/behind imagery.