The first thing is that I've been coming uncomfortably close to the public/private API when I added b720e72 (fetch: pass negotiation data around as a struct), a preparatory API cleanup because shallow clones need to keep track of some state when they're done. I originally had a git_array_oid_t in 99d7265 (WIP smart: negotiate server capabilities), but since that's private I can't put it in a public struct, hence I'm publishing a typedef-ed version of it (dunno if that's fine). It's either that or packing the array in a git_oidarray (public) and unpacking it afterward (as my first draft was doing). I think that's fine, but since we're aiming for API stability maybe it'd be best to split up at least that first commit before 1.0.

The second issue is that state I alluded to above : I've grown to be somewhat dubious of the amount of state going on in git_remote (the (active_|passive_|)refspecs members are an example of it). Now that I'm going to add a list of "future OIDs to shallow after the download is done", it's only getting worse, especially since the functions to perform a fetch are all public (ie. git_remote_fetch vs. git_remote_connect + git_remote_download vs. git_remote_push, all having a tendency to stomp over previous callers' work). Add to that that git_push is interwoven (1, 2, 3) into all of this and it's (IMHO) really confusing to know what's used when, by who. Especially update_tips is confusing : am I supposed to have shallowed the necessary OIDs before, or after it's done ? (that's rhetorical, since I did some checking to see how fetches are performed in cgit, and yet I'm still not sure…).

So I'm envisioning an API where git_remote is simplified by removing/deprecating its connect/disconnect/stop, download/upload/update_tips functions, and a new git_fetch object is made to parallel git_push. That would simplify the internals of git_remote and makes it clear where an operation's state is.

Ref: #2516, which has @carlosmn arguing for the other thing to happen : git_push gets merged in git_remote.

Merged in #6393