To not repeat past mistakes, do we maybe want to introduce an options struct here from the get-go? Doesn't need to contain anything options for now

I usually like having a default "do the default thing" and provide an _ext on top of that, if/when the need arises. But it feels a little premature (though only because of a lack of use cases, so if you have a definite not too difficult "this is needed" example, I'll reconsider).

Hmm. I would very quickly want progress reporting if I were to use this in anger. I concede that this is a bit tricky. I would definitely want, eg, progress reporting but many fields should not be eligible to be set by an end-user, so taking a whole git_clone_options may not be appropriate. Additionally, we may need to do some proxy'ing with some of the callbacks to ensure that payloads are delivered correctly.

Having said that, progress reporting and cancellation still feels like table-stakes for any function that does network I/O.

I usually like having a default "do the default thing" and provide an _ext on top of that, if/when the need arises.

Well, defaults are easily attainable by just passing NULL. Personally, I'm not too happy with the _ext suffix and I see it rather as a "Okay we f'd up the first time, so let's just tack on a suffix and fix up the function".

And yeah, fully agree with the usecases @ethomson proposes.

Hmm, yeah that's a tough decision. I can see pros and cons to simply taking a git_clone_options struct and just ignoring and overwriting parts of it (documenting this of course). Or a simpler struct and proxying that data into a git_clone_options.

The former seems like the simpler strategy for you (the implementer). What I'm not sure of is whether it's easier for users of the library, which is of course where I think the important bits are.

Simply taking git_clone_options is not going to fly in case there's going to be submodule-cloning specific options at some point in time, which I'd say is not all that unlikely. So I think it should definitely be a new git_submodule_clone_options struct, but as you said it may just embed and forward (parts of) the git_clone_options struct.

I've noticed that git_submodule_update_options seemed to have mostly what we needed, so I've added this as our option struct. Sorry, I forgot to rebase-ping, but IIRC it was ready to 🚢 as well.

Oh, didn't see that, sorry.

git_submodule_update_options does look similar to what we need, that's true. I'm still a bit hesitant, though. It includes options that cannot fit the bill right now and we may need to extend the struct for either git_submodule_update or git_submodule_clone with options that are incompatible with the respective other function. If you ask me, that's trading ease of implementation (no need for an additional struct) for a confusing API. I'm more in the camp of using one struct per function whenever it's not obvious that they're always going to take the same set of opts.

Just my 2 cents -- I'm happy to be overruled here due to my recent lack of time for libgit2.

(Struct for reference)

typedef struct git_submodule_update_options {
	unsigned int version;
	git_checkout_options checkout_opts;
	git_fetch_options fetch_opts;
	int allow_fetch;
} git_submodule_update_options;

Of theses, allow_fetch feels the most dubious, since we don't have any repository before the call. checkout seems fine (though I think there's a few rough edges), and fetch looks okay.

Now, I don't have that much experience with submodules, but a shared "those are the settings to obey if an update needs to happen", especially given the git submodule update --init --recursive thingie seems to be a nice thing. Writing in the docblock that allow_fetch only makes sense if the submodule is already initialized, and ignoring it if it's set seems sufficient.