buf: deprecate git_buf as a public typeethomson/userbuf

The `git_buf` type is now no longer a publicly available structure, and
the `git_buf` family of functions are no longer exported.

The deprecation layer adds a typedef for `git_buf` (as `git_userbuf`)
and macros that define `git_buf` functions as `git_userbuf` functions.
This provides API (but not ABI) compatibility with libgit2 1.0's buffer
functionality.

Within libgit2 itself, we take care to avoid including those deprecated
typedefs and macros, since we want to continue using the `git_buf` type
and functions unmodified.  Therefore, a `GIT_DEPRECATE_BUF` guard now
wraps the buffer deprecation layer.  libgit2 will define that.

23 files changed, 129 insertions, 183 deletions

diff --git a/include/git2.h b/include/git2.h
index f39d7fbe2..3fe64f4e4 100644
--- a/include/git2.h
+++ b/include/git2.h
@@ -14,7 +14,6 @@
 #include "git2/blob.h"
 #include "git2/blame.h"
 #include "git2/branch.h"
-#include "git2/buffer.h"
 #include "git2/cert.h"
 #include "git2/checkout.h"
 #include "git2/cherrypick.h"
diff --git a/include/git2/blob.h b/include/git2/blob.h
index 325ec44c5..1cf39eb1d 100644
--- a/include/git2/blob.h
+++ b/include/git2/blob.h
@@ -11,7 +11,6 @@
 #include "types.h"
 #include "oid.h"
 #include "object.h"
-#include "buffer.h"
 #include "userbuf.h"
 
 /**
diff --git a/include/git2/buffer.h b/include/git2/buffer.h
deleted file mode 100644
index 926f1332d..000000000
--- a/include/git2/buffer.h
+++ /dev/null
@@ -1,134 +0,0 @@
-/*
- * Copyright (C) the libgit2 contributors. All rights reserved.
- *
- * This file is part of libgit2, distributed under the GNU GPL v2 with
- * a Linking Exception. For full terms see the included COPYING file.
- */
-#ifndef INCLUDE_git_buf_h__
-#define INCLUDE_git_buf_h__
-
-#include "common.h"
-
-/**
- * @file git2/buffer.h
- * @brief Buffer export structure
- *
- * @ingroup Git
- * @{
- */
-GIT_BEGIN_DECL
-
-/**
- * A data buffer for exporting data from libgit2
- *
- * Sometimes libgit2 wants to return an allocated data buffer to the
- * caller and have the caller take responsibility for freeing that memory.
- * This can be awkward if the caller does not have easy access to the same
- * allocation functions that libgit2 is using.  In those cases, libgit2
- * will fill in a `git_buf` and the caller can use `git_buf_dispose()` to
- * release it when they are done.
- *
- * A `git_buf` may also be used for the caller to pass in a reference to
- * a block of memory they hold.  In this case, libgit2 will not resize or
- * free the memory, but will read from it as needed.
- *
- * Some APIs may occasionally do something slightly unusual with a buffer,
- * such as setting `ptr` to a value that was passed in by the user.  In
- * those cases, the behavior will be clearly documented by the API.
- */
-typedef struct {
-	/**
-	 * The buffer contents.
-	 *
-	 * `ptr` points to the start of the allocated memory.  If it is NULL,
-	 * then the `git_buf` is considered empty and libgit2 will feel free
-	 * to overwrite it with new data.
-	 */
-	char   *ptr;
-
-	/**
-	 * `asize` holds the known total amount of allocated memory if the `ptr`
-	 *  was allocated by libgit2.  It may be larger than `size`.  If `ptr`
-	 *  was not allocated by libgit2 and should not be resized and/or freed,
-	 *  then `asize` will be set to zero.
-	 */
-	size_t asize;
-
-	/**
-	 * `size` holds the size (in bytes) of the data that is actually used.
-	 */
-	size_t size;
-} git_buf;
-
-/**
- * Static initializer for git_buf from static buffer
- */
-#define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) }
-
-/**
- * Free the memory referred to by the git_buf.
- *
- * Note that this does not free the `git_buf` itself, just the memory
- * pointed to by `buffer->ptr`.  This will not free the memory if it looks
- * like it was not allocated internally, but it will clear the buffer back
- * to the empty state.
- *
- * @param buffer The buffer to deallocate
- */
-GIT_EXTERN(void) git_buf_dispose(git_buf *buffer);
-
-/**
- * Resize the buffer allocation to make more space.
- *
- * This will attempt to grow the buffer to accommodate the target size.
- *
- * If the buffer refers to memory that was not allocated by libgit2 (i.e.
- * the `asize` field is zero), then `ptr` will be replaced with a newly
- * allocated block of data.  Be careful so that memory allocated by the
- * caller is not lost.  As a special variant, if you pass `target_size` as
- * 0 and the memory is not allocated by libgit2, this will allocate a new
- * buffer of size `size` and copy the external data into it.
- *
- * Currently, this will never shrink a buffer, only expand it.
- *
- * If the allocation fails, this will return an error and the buffer will be
- * marked as invalid for future operations, invaliding the contents.
- *
- * @param buffer The buffer to be resized; may or may not be allocated yet
- * @param target_size The desired available size
- * @return 0 on success, -1 on allocation failure
- */
-GIT_EXTERN(int) git_buf_grow(git_buf *buffer, size_t target_size);
-
-/**
- * Set buffer to a copy of some raw data.
- *
- * @param buffer The buffer to set
- * @param data The data to copy into the buffer
- * @param datalen The length of the data to copy into the buffer
- * @return 0 on success, -1 on allocation failure
- */
-GIT_EXTERN(int) git_buf_set(
-	git_buf *buffer, const void *data, size_t datalen);
-
-/**
-* Check quickly if buffer looks like it contains binary data
-*
-* @param buf Buffer to check
-* @return 1 if buffer looks like non-text data
-*/
-GIT_EXTERN(int) git_buf_is_binary(const git_buf *buf);
-
-/**
-* Check quickly if buffer contains a NUL byte
-*
-* @param buf Buffer to check
-* @return 1 if buffer contains a NUL byte
-*/
-GIT_EXTERN(int) git_buf_contains_nul(const git_buf *buf);
-
-GIT_END_DECL
-
-/** @} */
-
-#endif
diff --git a/include/git2/deprecated.h b/include/git2/deprecated.h
index 7be6bb258..9fd4489a9 100644
--- a/include/git2/deprecated.h
+++ b/include/git2/deprecated.h
@@ -11,7 +11,6 @@
 #include "config.h"
 #include "common.h"
 #include "blame.h"
-#include "buffer.h"
 #include "checkout.h"
 #include "cherrypick.h"
 #include "clone.h"
@@ -123,17 +122,23 @@ GIT_EXTERN(int) git_blob_filtered_content(
  */
 /**@{*/
 
-/**
- * Free the memory referred to by the git_buf.  This is an alias of
- * `git_buf_dispose` and is preserved for backward compatibility.
- *
- * This function is deprecated, but there is no plan to remove this
- * function at this time.
- *
- * @deprecated Use git_buf_dispose
- * @see git_buf_dispose
+/*
+ * You may hard-deprecate only the git_buf compatibility layer by
+ * setting GIT_DEPRECATE_BUF.
  */
-GIT_EXTERN(void) git_buf_free(git_buf *buffer);
+#ifndef GIT_DEPRECATE_BUF
+
+typedef git_userbuf git_buf;
+
+#define GIT_BUF_INIT_CONST(str, len) GIT_USERBUF_CONST(str, len)
+#define git_buf_set(buf, data, datalen) git_userbuf_set(buf, data, datalen)
+#define git_buf_grow(buf, size) git_userbuf_grow(buf, size)
+#define git_buf_is_binary(b) git_userbuf_is_binary(b)
+#define git_buf_contains_nul(b) git_userbuf_contains_nul(b)
+#define git_buf_dispose(b) git_userbuf_dispose(b)
+#define git_buf_free(b) git_userbuf_dispose(b)
+
+#endif /* GIT_DEPRECATE_BUF */
 
 /**@}*/
 
diff --git a/include/git2/describe.h b/include/git2/describe.h
index d53d9e81f..bca14aa59 100644
--- a/include/git2/describe.h
+++ b/include/git2/describe.h
@@ -9,7 +9,7 @@
 
 #include "common.h"
 #include "types.h"
-#include "buffer.h"
+#include "userbuf.h"
 
 /**
  * @file git2/describe.h
diff --git a/include/git2/filter.h b/include/git2/filter.h
index 01a8e86a8..383c23fdc 100644
--- a/include/git2/filter.h
+++ b/include/git2/filter.h
@@ -10,7 +10,7 @@
 #include "common.h"
 #include "types.h"
 #include "oid.h"
-#include "buffer.h"
+#include "userbuf.h"
 
 /**
  * @file git2/filter.h
diff --git a/include/git2/mailmap.h b/include/git2/mailmap.h
index 7c3f60fcc..4ac972957 100644
--- a/include/git2/mailmap.h
+++ b/include/git2/mailmap.h
@@ -9,7 +9,6 @@
 
 #include "common.h"
 #include "types.h"
-#include "buffer.h"
 
 /**
  * @file git2/mailmap.h
diff --git a/include/git2/message.h b/include/git2/message.h
index 98078fe02..aa6e0c72c 100644
--- a/include/git2/message.h
+++ b/include/git2/message.h
@@ -8,7 +8,6 @@
 #define INCLUDE_git_message_h__
 
 #include "common.h"
-#include "buffer.h"
 #include "userbuf.h"
 
 /**
diff --git a/include/git2/object.h b/include/git2/object.h
index 9f9131bbe..f8fdb2271 100644
--- a/include/git2/object.h
+++ b/include/git2/object.h
@@ -10,7 +10,7 @@
 #include "common.h"
 #include "types.h"
 #include "oid.h"
-#include "buffer.h"
+#include "userbuf.h"
 
 /**
  * @file git2/object.h
diff --git a/include/git2/refspec.h b/include/git2/refspec.h
index 5676c1ab9..6ff4558c7 100644
--- a/include/git2/refspec.h
+++ b/include/git2/refspec.h
@@ -10,7 +10,7 @@
 #include "common.h"
 #include "types.h"
 #include "net.h"
-#include "buffer.h"
+#include "userbuf.h"
 
 /**
  * @file git2/refspec.h
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 8b61cd5b7..3265b2e6b 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -10,7 +10,6 @@
 #include "common.h"
 #include "types.h"
 #include "oid.h"
-#include "buffer.h"
 #include "userbuf.h"
 
 /**
diff --git a/include/git2/sys/mempack.h b/include/git2/sys/mempack.h
index e869589a1..70d3725c6 100644
--- a/include/git2/sys/mempack.h
+++ b/include/git2/sys/mempack.h
@@ -11,7 +11,7 @@
 #include "git2/types.h"
 #include "git2/oid.h"
 #include "git2/odb.h"
-#include "git2/buffer.h"
+#include "git2/userbuf.h"
 
 /**
  * @file git2/sys/mempack.h
diff --git a/include/git2/types.h b/include/git2/types.h
index ade0c7d32..e9d7a6ce6 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -66,7 +66,6 @@ typedef int64_t git_time_t; /**< time in seconds from epoch */
 /** The maximum size of an object */
 typedef uint64_t git_object_size_t;
 
-#include "buffer.h"
 #include "oid.h"
 
 /** Basic type (loose or packed) of any Git object. */
diff --git a/include/git2/userbuf.h b/include/git2/userbuf.h
index 4fe8ccf47..2e498914a 100644
--- a/include/git2/userbuf.h
+++ b/include/git2/userbuf.h
@@ -28,9 +28,9 @@ GIT_BEGIN_DECL
  * A data buffer for exporting data from libgit2.
  *
  * Sometimes libgit2 wants to return an allocated data buffer to the
- * caller and have the caller take responsibility for freeing that memory.
- * This structure should be freed with `git_userbuf_dispose` when you
- * have finished with it.
+ * caller and allow the caller take responsibility for its lifecycle.
+ * This requires the caller to free the memory with `git_userbuf_dispose`
+ * when they have finished using it.
  */
 typedef struct {
 	/**
@@ -54,6 +54,22 @@ typedef struct {
 } git_userbuf;
 
 /**
+ * Check quickly if buffer looks like it contains binary data
+ *
+ * @param buf Buffer to check
+ * @return 1 if buffer looks like non-text data
+ */
+GIT_EXTERN(int) git_userbuf_is_binary(const git_userbuf *buf);
+
+ /**
+ * Check quickly if buffer contains a NUL byte
+ *
+ * @param buf Buffer to check
+ * @return 1 if buffer contains a NUL byte
+ */
+GIT_EXTERN(int) git_userbuf_contains_nul(const git_userbuf *buf);
+
+/**
  * Places the given data in the buffer.  This is necessary for some
  * callback functions that take user data.  If there is already data in
  * the buffer, you should call `git_userbuf_dispose` before setting the
@@ -63,7 +79,30 @@ typedef struct {
  * @param ptr The data to place in the buffer
  * @param len The length of the data in bytes
  */
-GIT_EXTERN(int) git_userbuf_set(git_userbuf *buf, const char *ptr, size_t len);
+GIT_EXTERN(int) git_userbuf_set(git_userbuf *buf, const void *ptr, size_t len);
+
+/**
+ * Resize the buffer allocation to make more space.
+ *
+ * This will attempt to grow the buffer to accommodate the target size.
+ *
+ * If the buffer refers to memory that was not allocated by libgit2 (i.e.
+ * the `asize` field is zero), then `ptr` will be replaced with a newly
+ * allocated block of data.  Be careful so that memory allocated by the
+ * caller is not lost.  As a special variant, if you pass `target_size` as
+ * 0 and the memory is not allocated by libgit2, this will allocate a new
+ * buffer of size `size` and copy the external data into it.
+ *
+ * Currently, this will never shrink a buffer, only expand it.
+ *
+ * If the allocation fails, this will return an error and the buffer will be
+ * marked as invalid for future operations, invaliding the contents.
+ *
+ * @param buffer The buffer to be resized; may or may not be allocated yet
+ * @param target_size The desired available size
+ * @return 0 on success, -1 on allocation failure
+ */
+GIT_EXTERN(int) git_userbuf_grow(git_userbuf *buffer, size_t target_size);
 
 /**
  * Free the memory referred to by the git_userbuf.
diff --git a/include/git2/worktree.h b/include/git2/worktree.h
index bda916d96..bd7420c74 100644
--- a/include/git2/worktree.h
+++ b/include/git2/worktree.h
@@ -8,7 +8,6 @@
 #define INCLUDE_git_worktree_h__
 
 #include "common.h"
-#include "buffer.h"
 #include "userbuf.h"
 #include "types.h"
 #include "strarray.h"
diff --git a/src/buffer.c b/src/buffer.c
index f81f19999..ce97ccffa 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -6,7 +6,7 @@
  */
 #include "buffer.h"
 #include "posix.h"
-#include "git2/buffer.h"
+#include "git2/userbuf.h"
 #include "buf_text.h"
 #include <ctype.h>
 
@@ -181,16 +181,6 @@ int git_buf_set(git_buf *buf, const void *data, size_t len)
 	return 0;
 }
 
-int git_buf_is_binary(const git_buf *buf)
-{
-	return git_buf_text_is_binary(buf);
-}
-
-int git_buf_contains_nul(const git_buf *buf)
-{
-	return git_buf_text_contains_nul(buf);
-}
-
 int git_buf_sets(git_buf *buf, const char *string)
 {
 	return git_buf_set(buf, string, string ? strlen(string) : 0);
diff --git a/src/buffer.h b/src/buffer.h
index a2ac2c77b..e2023cc59 100644
--- a/src/buffer.h
+++ b/src/buffer.h
@@ -9,13 +9,12 @@
 
 #include "common.h"
 #include "git2/strarray.h"
-#include "git2/buffer.h"
+#include "git2/userbuf.h"
 
-/* typedef struct {
- *  	char   *ptr;
- *  	size_t asize, size;
- * } git_buf;
- */
+typedef struct {
+	char *ptr;
+	size_t asize, size;
+} git_buf;
 
 extern char git_buf__initbuf[];
 extern char git_buf__oom[];
@@ -23,6 +22,9 @@ extern char git_buf__oom[];
 /* Use to initialize buffer structure when git_buf is on stack */
 #define GIT_BUF_INIT { git_buf__initbuf, 0, 0 }
 
+/* Static initializer for git_buf from static buffer */
+#define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) }
+
 GIT_INLINE(bool) git_buf_is_allocated(const git_buf *buf)
 {
 	return (buf->ptr != NULL && buf->asize > 0);
@@ -37,6 +39,36 @@ GIT_INLINE(bool) git_buf_is_allocated(const git_buf *buf)
 extern int git_buf_init(git_buf *buf, size_t initial_size);
 
 /**
+ * Dispose the git_buf.  If the memory is owned by libgit2 (in other
+ * words, if asize > 0) then the given ptr will be freed.
+ */
+extern void git_buf_dispose(git_buf *buf);
+
+/**
+ * Sets the buffer to a copy of some raw data.
+ */
+extern int git_buf_set(git_buf *buf, const void *ptr, size_t len);
+
+/**
+ * Resize the buffer allocation to make more space.
+ *
+ * This will attempt to grow the buffer to accommodate the target size.
+ *
+ * If the buffer refers to memory that was not allocated by libgit2 (i.e.
+ * the `asize` field is zero), then `ptr` will be replaced with a newly
+ * allocated block of data.  Be careful so that memory allocated by the
+ * caller is not lost.  As a special variant, if you pass `target_size` as
+ * 0 and the memory is not allocated by libgit2, this will allocate a new
+ * buffer of size `size` and copy the external data into it.
+ *
+ * Currently, this will never shrink a buffer, only expand it.
+ *
+ * If the allocation fails, this will return an error and the buffer will
+ * be marked as invalid for future operations, invaliding the contents.
+*/
+extern int git_buf_grow(git_buf *buf, size_t size);
+
+/**
  * Resize the buffer allocation to make more space.
  *
  * This will attempt to grow the buffer to accommodate the additional size.
diff --git a/src/common.h b/src/common.h
index 2b1a4a456..dc3062223 100644
--- a/src/common.h
+++ b/src/common.h
@@ -85,7 +85,13 @@
 /*
  * Include the declarations for deprecated functions; this ensures
  * that they're decorated with the proper extern/visibility attributes.
+ *
+ * Before doing that, declare that we don't want compatibility git_buf
+ * definitions.  We want to avoid intermingling the public compatibility
+ * layer with our actual git_buf types and functions.
  */
+
+#define GIT_DEPRECATE_BUF
 #include "git2/deprecated.h"
 
 #include "posix.h"
diff --git a/src/transports/auth_ntlm.c b/src/transports/auth_ntlm.c
index d134a3db6..12000e665 100644
--- a/src/transports/auth_ntlm.c
+++ b/src/transports/auth_ntlm.c
@@ -5,8 +5,8 @@
  * a Linking Exception. For full terms see the included COPYING file.
  */
 
-#include "git2.h"
 #include "common.h"
+#include "git2.h"
 #include "buffer.h"
 #include "auth.h"
 #include "auth_ntlm.h"
diff --git a/src/userbuf.c b/src/userbuf.c
index e5c8fa3b7..5bfb27ae0 100644
--- a/src/userbuf.c
+++ b/src/userbuf.c
@@ -4,9 +4,9 @@
  * This file is part of libgit2, distributed under the GNU GPL v2 with
  * a Linking Exception. For full terms see the included COPYING file.
  */
+
 #include "userbuf.h"
 #include "buffer.h"
-#include "git2/buffer.h"
 #include "buf_text.h"
 #include <ctype.h>
 
@@ -21,11 +21,26 @@ void git_userbuf_sanitize(git_userbuf *buf)
 	}
 }
 
-int git_userbuf_set(git_userbuf *buf, const char *ptr, size_t len)
+int git_userbuf_is_binary(const git_userbuf *buf)
+{
+	return git_buf_text_is_binary((git_buf *)buf);
+}
+
+int git_userbuf_contains_nul(const git_userbuf *buf)
+{
+	return git_buf_text_contains_nul((git_buf *)buf);
+}
+
+int git_userbuf_set(git_userbuf *buf, const void *ptr, size_t len)
 {
 	return git_buf_set((git_buf *)buf, ptr, len);
 }
 
+int git_userbuf_grow(git_userbuf *buf, size_t size)
+{
+	return git_buf_grow((git_buf *)buf, size);
+}
+
 void git_userbuf_dispose(git_userbuf *buf)
 {
 	git_buf_dispose((git_buf *)buf);
diff --git a/src/userbuf.h b/src/userbuf.h
index 3d7a837d5..faa91fe16 100644
--- a/src/userbuf.h
+++ b/src/userbuf.h
@@ -7,6 +7,7 @@
 #ifndef INCLUDE_userbuf_h__
 #define INCLUDE_userbuf_h__
 
+#include "common.h"
 #include "git2/userbuf.h"
 #include "buffer.h"
 
diff --git a/src/util.h b/src/util.h
index af38698fe..06a10f58e 100644
--- a/src/util.h
+++ b/src/util.h
@@ -13,8 +13,6 @@
 # include <ctype.h>
 #endif
 
-#include "git2/buffer.h"
-
 #include "buffer.h"
 #include "common.h"
 #include "strnlen.h"
diff --git a/tests/stream/deprecated.c b/tests/stream/deprecated.c
index 2c2bbfdc3..c9b15d16f 100644
--- a/tests/stream/deprecated.c
+++ b/tests/stream/deprecated.c
@@ -1,4 +1,5 @@
 #undef GIT_DEPRECATE_HARD
+#define GIT_DEPRECATE_BUF
 
 #include "clar_libgit2.h"
 #include "git2/sys/stream.h"