> On Sun, Dec 09, 2018 at 09:51:28AM +0900, Junio C Hamano wrote: > > > > -static int parse_commit_in_graph_one(struct commit_graph *g, struct > > > commit *item) > > > +static struct commit *parse_commit_in_graph_one(struct repository *r, > > > + struct commit_graph *g, > > > + struct commit *shell, > > > + const struct object_id *oid) > > > > Now the complexity of the behaviour of this function deserves to be > > documented in a comment in front. Let me see if I can get it > > correctly without such a comment by explaining the function aloud. > > > > The caller may or may not have already obtained an in-core commit > > object for a given object name, so shell could be NULL but otherwise > > it could be used for optimization. When shell==NULL, the function > > looks up the commit object using the oid parameter instead. The > > returned in-core commit has the parents etc. filled as if we ran > > parse_commit() on it. If the commit is not yet in the graph, the > > caller may get a NULL even if the commit exists.
In the next revision, I'll unify parse_commit_in_graph_one() (quoted above) with parse_commit_in_graph(), so that the comment I wrote for the latter can cover the entire functionality. I think the comment covers the details that you outline here. > Yeah, this was the part that took me a bit to figure out, as well. The > optimization here is really just avoiding a call to lookup_commit(), > which will do a single hash-table lookup. I wonder if that's actually > worth this more complex interface (as opposed to just always taking an > oid and then always returning a "struct commit", which could be old or > new). Avoidance of lookup_commit() is more important than an optimization, I think. Here, we call lookup_commit() only when we know that that object is a commit (by its presence in a commit graph). If we just called it blindly, we might mistakenly create a commit for that hash when it is actually an object of another type. (We could inline lookup_commit() in parse_commit_in_graph_one(), removing the object creation part, but that adds complexity as well.)
