Probably worth commenting that no validation is done on the signature, and that the user needs to generate the signature themselves. (If you're feeling particularly generous it would be nice to show in the comment the way to generate a signature that matches the default gpgsig key)

While we can make the working more explicit about the caller providing the signature, I don't see that we hint at the library performing validation anywhere. I'd worry that adding such a comment would imply that validation is the norm.

Figuring out how to shell out to your favourite program is a problem domain which libgit2 stays away from. Even a simplified example would be problematic.

Yep, I agree that shelling out is completely out of line for libgit2. However I'd assume a user could link with gpg and use its functions to get what they need for a signature.

Git picks up and uses gpg automatically, which also isn't appropriate here, but is partly why I think its worth making things a little more obvious for the user.

A change to the wording here (and maybe wherever else we do signing in the same kind of way) would suffice IMO, since just reading the function comments doesn't really give the use much of an idea how to actually hook this all together to produce something correct. And the fun part is its relatively easy to hook it all together in a way that it runs, and has an incorrect signature... (since we don't (can't) validate the provided signature)

(Note - I don't envisage me ever using this function - signing commits is something I've not had to do in the past and surely don't envisage having to hook it into my applications. I'm purely considering other potential users here - and maybe they're all savvy enough that my concerns are moot...)

I agree with @mikeando that it would be nice to have some nice documentation around here. I think that we're still building the pieces that will let you work with signed commits. It's going to take a while to get this done and then to get it right. Until then, though, I don't want to spend a lot of time documenting moving parts. Instead, let's document it nicely and build an example once we're done.

Really cool to see this functionality being added to libgit2! I think this will open up really cool features for applications being built on libgit2 (like GitKraken) to enable gpg signing/verification. Glad there is progress being made here in tooling!

However, this PR rather disappointing from the consumer side of things that this is all libgit2 appears to be planning for commit signing. I understand you don't want to shell out or bring in a gpg dependency. Totally get that. But I think you could do more here for a fully-fledged git commit signature api.

Granted, I'm just now looking at libgit2 for the first time, but I have no clue how one should go about constructing the commit_content string. I don't see anything that does this for you in commit.h.

Better ways of doing this that come to mind:

1. Make git_commit_create_with_signature take all the same parameters as git_commit_create as well as signature_field and a signature_callback function that calculates the signature from the given commit contents string. This may not be a pattern libgit2 uses, and maybe there's some memory ownership issues here since this is a C api and we can't use std::string.
2. First make the user call git_commit_create_buffer to create the commit in a git_buf (or some other intermediate structure?), and then have git_commit_create_with_signature take the git_buf * instead of an unstructured const char *.

Hope you can see from this side of things this function feels like a (really exciting!) bridge halfway... 😢

@carlosmn I noticed that I can create signed commits but no reference is created. I'm going to dig into the source to verify but I wanted to ask (as it's not covered here). I guess it should be expected though as no ref is passed to either function.