graph: make the ahead-behind docs clearer Explain it in local-upstream branch terms so it's easier to grasp than with the `one` and `two` naming from the merge-base code.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
diff --git a/include/git2/graph.h b/include/git2/graph.h
index 5850aa6..a271021 100644
--- a/include/git2/graph.h
+++ b/include/git2/graph.h
@@ -23,13 +23,18 @@ GIT_BEGIN_DECL
/**
* Count the number of unique commits between two commit objects
*
- * @param ahead number of commits, starting at `one`, unique from commits in `two`
- * @param behind number of commits, starting at `two`, unique from commits in `one`
+ * There is no need for branches containing the commits to have any
+ * upstream relationship, but it helps to think of one as a branch and
+ * the other as its upstream, the `ahead` and `behind` values will be
+ * what git would report for the branches.
+ *
+ * @param ahead number of unique from commits in `upstream`
+ * @param behind number of unique from commits in `local`
* @param repo the repository where the commits exist
- * @param one one of the commits
- * @param two the other commit
+ * @param local the commit for local
+ * @param upstream the commit for upstream
*/
-GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *one, const git_oid *two);
+GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *local, const git_oid *upstream);
/** @} */
GIT_END_DECL
diff --git a/src/graph.c b/src/graph.c
index cb17279..277f588 100644
--- a/src/graph.c
+++ b/src/graph.c
@@ -147,25 +147,25 @@ on_error:
}
int git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo,
- const git_oid *one, const git_oid *two)
+ const git_oid *local, const git_oid *upstream)
{
git_revwalk *walk;
- git_commit_list_node *commit1, *commit2;
+ git_commit_list_node *commit_u, *commit_l;
if (git_revwalk_new(&walk, repo) < 0)
return -1;
- commit2 = git_revwalk__commit_lookup(walk, two);
- if (commit2 == NULL)
+ commit_u = git_revwalk__commit_lookup(walk, upstream);
+ if (commit_u == NULL)
goto on_error;
- commit1 = git_revwalk__commit_lookup(walk, one);
- if (commit1 == NULL)
+ commit_l = git_revwalk__commit_lookup(walk, local);
+ if (commit_l == NULL)
goto on_error;
- if (mark_parents(walk, commit1, commit2) < 0)
+ if (mark_parents(walk, commit_l, commit_u) < 0)
goto on_error;
- if (ahead_behind(commit1, commit2, ahead, behind) < 0)
+ if (ahead_behind(commit_l, commit_u, ahead, behind) < 0)
goto on_error;
git_revwalk_free(walk);