Introduce git_merge_file for consumers

[ethomson]

• Add a git-merge-file like API that allows callers to merge files as they exist on disk (that may or may not exist in a repository)
• Add a git-merge-file API that allows callers to reproduce the results of checking out a single conflicted file
• Tests!
• Update docs in the headers
• Fancy new struct initializer functions

[ethomson]

So I think that the second point hits consumers like @mhodgson (in his request over in #2119.)

After writing the first point, I think it's not what we actually want, I think we want to take a git_bufs instead. Arguments?

@vmg you mentioned that you might expect a callback here - since xdiff does all this in memory, I would expect to splat this back in a struct, along with the metadata (the resultant filename and mode, selected from the changed entry).

[vmg]

Brilliant. You're right, since Xdiff is gonna keep everything in memory, we might as well return it as a single struct. The only thing I'd consider is embedding a git_buf inside the result struct... This would even allow us to get rid of the git_merge_result_free call, as the buffer could be freed by the existing API and everything else could (and should) be stack allocated.

[ethomson]

Aren't you clever. I'll take a whack at that.

[vmg]

@ethomson called me cleveeeer

[ethomson]

Okay, I'm pretty happy with this and would like another set of eyes. I refactored this a bit and as a result exposed git_merge_file_input instead of trying to expose a raft of functions that tried to aide consumers in doing the merge. The result struct adds the path buffer, now. (After the refactoring, it didn't seem to be a big benefit to make the output a git_buf.)

[arthurschreiber]

I like it. ❤️

[mhodgson]

Dig it. I updated the rugged bindings. Should be good to go once we get this merged. Just need to write a few tests once I can build against this.

[jacquesg]

👍 Any chance of us getting custom merge driver support soon?

[ethomson]

@jacquesg That's a good question, and a big topic. Would you mind opening a separate issue?

[jacquesg]

Will do.

[ethomson]

So! Any comments or complaints on this one?

[ethomson]

Closed via #2183