Sheesh. Has anybody else noticed that my verbosity in the PR comments is inversely proportional to the length of the pull request?

@ethomson Case in point: #1007

Looks good to me. I'm a little on the fence if we should be checking the user input using an assert in this case or if we should be using a regular check with giterr_set if the buf content are non-compliant, but it's probably fine.

I assume we'll use this anywhere that we take a buf from the user that they are responsible for having initialized, which I guess means that the filter code doesn't need it now because the buffers in use there are always initialized by libgit2 internally, I believe. Does that seem right?

Obviously we could make more aggressive changes here - we could ensure that users always create git_bufs with some sort of init method, or we could drop the assumption that git_bufs are always null terminated, but those both seem unnecessary and this seems to me like a good middle ground.

Please reconsider the idea of forcing users to initialise git_bufs in the same way other input-structs are initialised. Having lots of similar structured APIs decreases the learning curve a lot. This doesn't look like it's really worth to change the usage pattern here. In other words: writing git_buf buf = GIT_INIT_BUF; seems much more natural (than any other way to init it) in the context of libgit2 API.

@scunz The problem isn't git_buf buf = GIT_BUF_INIT for C / C++ users. We can expose that if you want, but it doesn't help authors of bindings that can't take advantage of C macros - in this case, LibGit2Sharp. They need a similar mechanism: to not accept NULL in ptr means that C# users would have to marshal an empty string just to use these functions, which is sort of crazy.

What I meant was an actual git_buf_init function. This is less onerous than the bindings knowing that they have to marshal an empty string for no seemingly good reason. But I would rather not need to do that at all, I would rather just pass a null.

I assume we'll use this anywhere that we take a buf from the user that they are responsible for having initialized, which I guess means that the filter code doesn't need it now because the buffers in use there are always initialized by libgit2 internally, I believe. Does that seem right?

This matches my thinking!

I like @scunz 's idea of exposing GIT_BUF_INIT to the big bad world. @arrbee any objections? If not, I'll add that to this PR.

My only concern is that will also require exposing git_buf__initbuf and we used to do something similar with attributes and it caused tons of linkage problems. I think there is some complexity with exporting data symbols in a portable manner.

Yeah. We could do it with NULL now, instead of with git_buf__initbuf... but only for consumers, and we'd have to have a separate macro for consumers and internal. Bluh. Let's not muddy the sweet, sweet waters of this PR with that quite yet.

Looks very clean. Exporting GIT_BUF_INIT is not an option (unfortunately) because git_buf__initbuf is linkage hell. However, we could export an alternative that sets NULL instead.