sha256: simplify API changes for sha256 support

There are several places where users may want to specify the type of
object IDs (sha1 or sha256) that should be used, for example, when
dealing with repositories, indexes, etc.

However, given that sha256 support remains disappointingly uncommon in
the wild, we should avoid hard API breaks when possible. Instead, update
these APIs to have an "extended" format (eg, `git_odb_open_ext`) that
provides an options structure with oid type information.

This allows callers who do care about sha256 to use it, and callers who
do not to avoid gratuitous API breakage.

Author: ethomson

examples/diff.c

@@ -189,15 +189,9 @@ static void compute_diff_no_index(git_diff **diff, struct diff_options *o) {
 		git_patch_to_buf(&buf, patch),
 		"patch to buf", NULL);
 
-#ifdef GIT_EXPERIMENTAL_SHA256
-	check_lg2(
-		git_diff_from_buffer(diff, buf.ptr, buf.size, NULL),
-		"diff from patch", NULL);
-#else
 	check_lg2(
 		git_diff_from_buffer(diff, buf.ptr, buf.size),
 		"diff from patch", NULL);
-#endif
 
 	git_patch_free(patch);
 	git_buf_dispose(&buf);

examples/show-index.c

@@ -30,11 +30,7 @@ int lg2_show_index(git_repository *repo, int argc, char **argv)
 
 	dirlen = strlen(dir);
 	if (dirlen > 5 && strcmp(dir + dirlen - 5, "index") == 0) {
-#ifdef GIT_EXPERIMENTAL_SHA256
-		check_lg2(git_index_open(&index, dir, NULL), "could not open index", dir);
-#else
 		check_lg2(git_index_open(&index, dir), "could not open index", dir);
-#endif
 	} else {
 		check_lg2(git_repository_open_ext(&repo, dir, 0, NULL), "could not open repository", dir);
 		check_lg2(git_repository_index(&index, repo), "could not open repository index", NULL);

fuzzers/packfile_fuzzer.c

@@ -37,17 +37,10 @@ int LLVMFuzzerInitialize(int *argc, char ***argv)
 		abort();
 	}
 
-#ifdef GIT_EXPERIMENTAL_SHA256
-	if (git_odb_new(&odb, NULL) < 0) {
-		fprintf(stderr, "Failed to create the odb\n");
-		abort();
-	}
-#else
 	if (git_odb_new(&odb) < 0) {
 		fprintf(stderr, "Failed to create the odb\n");
 		abort();
 	}
-#endif
 
 	if (git_mempack_new(&mempack) < 0) {
 		fprintf(stderr, "Failed to create the mempack\n");

include/git2/diff.h

@@ -1321,6 +1321,8 @@ GIT_EXTERN(int) git_diff_buffers(
  */
 typedef struct {
 	unsigned int version;
+
+	/** Object ID type used in the patch file. */
 	git_oid_t oid_type;
 } git_diff_parse_options;
 
@@ -1330,8 +1332,7 @@ typedef struct {
 /** Stack initializer for diff parse options.  Alternatively use
  * `git_diff_parse_options_init` programmatic initialization.
  */
-#define GIT_DIFF_PARSE_OPTIONS_INIT \
-	{ GIT_DIFF_PARSE_OPTIONS_VERSION, GIT_OID_DEFAULT }
+#define GIT_DIFF_PARSE_OPTIONS_INIT { GIT_DIFF_PARSE_OPTIONS_VERSION }
 
 /**
  * Read the contents of a git patch file into a `git_diff` object.
@@ -1347,6 +1348,9 @@ typedef struct {
  * implementation, it will not read unified diffs produced by
  * the `diff` program, nor any other types of patch files.
  *
+ * @note This API only supports SHA1 patch files
+ * @see git_diff_from_buffer_ext
+ *
  * @param out A pointer to a git_diff pointer that will be allocated.
  * @param content The contents of a patch file
  * @param content_len The length of the patch file contents
@@ -1355,11 +1359,37 @@ typedef struct {
 GIT_EXTERN(int) git_diff_from_buffer(
 	git_diff **out,
 	const char *content,
-	size_t content_len
+	size_t content_len);
+
 #ifdef GIT_EXPERIMENTAL_SHA256
-	, git_diff_parse_options *opts
+
+/**
+ * Read the contents of a git patch file into a `git_diff` object.
+ *
+ * The diff object produced is similar to the one that would be
+ * produced if you actually produced it computationally by comparing
+ * two trees, however there may be subtle differences.  For example,
+ * a patch file likely contains abbreviated object IDs, so the
+ * object IDs in a `git_diff_delta` produced by this function will
+ * also be abbreviated.
+ *
+ * This function will only read patch files created by a git
+ * implementation, it will not read unified diffs produced by
+ * the `diff` program, nor any other types of patch files.
+ *
+ * @param out A pointer to a git_diff pointer that will be allocated.
+ * @param content The contents of a patch file
+ * @param content_len The length of the patch file contents
+ * @param opts Options controlling diff parsing
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_diff_from_buffer_ext(
+	git_diff **out,
+	const char *content,
+	size_t content_len,
+	git_diff_parse_options *opts);
+
 #endif
-	);
 
 /**
  * This is an opaque structure which is allocated by `git_diff_get_stats`.

include/git2/index.h

@@ -189,8 +189,6 @@ typedef enum {
 	GIT_INDEX_STAGE_THEIRS = 3
 } git_index_stage_t;
 
-#ifdef GIT_EXPERIMENTAL_SHA256
-
 /**
  * The options for opening or creating an index.
  *
@@ -233,62 +231,76 @@ GIT_EXTERN(int) git_index_options_init(
 	unsigned int version);
 
 /**
- * Creates a new bare Git index object, without a repository to back
- * it. This index object is capable of storing SHA256 objects.
+ * Create a new bare Git index object as a memory representation
+ * of the Git index file in 'index_path', without a repository
+ * to back it.
+ *
+ * Since there is no ODB or working directory behind this index,
+ * any Index methods which rely on these (e.g. index_add_bypath)
+ * will fail with the GIT_ERROR error code.
+ *
+ * If you need to access the index of an actual repository,
+ * use the `git_repository_index` wrapper.
+ *
+ * The index must be freed once it's no longer in use.
+ *
+ * @note This API only supports SHA1 indexes
+ * @see git_index_open_ext
  *
  * @param index_out the pointer for the new index
  * @param index_path the path to the index file in disk
- * @param opts the options for opening the index, or NULL
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_index_open(
 	git_index **index_out,
-	const char *index_path,
-	const git_index_options *opts);
+	const char *index_path);
+
+#ifdef GIT_EXPERIMENTAL_SHA256
 
 /**
- * Create an in-memory index object.
+ * Creates a new bare Git index object, without a repository to back
+ * it. This index object is capable of storing SHA256 objects.
  *
  * @param index_out the pointer for the new index
+ * @param index_path the path to the index file in disk
  * @param opts the options for opening the index, or NULL
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_index_new(git_index **index_out, const git_index_options *opts);
+GIT_EXTERN(int) git_index_open_ext(
+	git_index **index_out,
+	const char *index_path,
+	const git_index_options *opts);
 
-#else
+#endif
 
 /**
- * Create a new bare Git index object as a memory representation
- * of the Git index file in 'index_path', without a repository
- * to back it.
- *
- * Since there is no ODB or working directory behind this index,
- * any Index methods which rely on these (e.g. index_add_bypath)
- * will fail with the GIT_ERROR error code.
+ * Create an in-memory index object.
  *
- * If you need to access the index of an actual repository,
- * use the `git_repository_index` wrapper.
+ * This index object cannot be read/written to the filesystem,
+ * but may be used to perform in-memory index operations.
  *
  * The index must be freed once it's no longer in use.
  *
+ * @note This API only supports SHA1 indexes
+ * @see git_index_new_ext
+ *
  * @param index_out the pointer for the new index
- * @param index_path the path to the index file in disk
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_index_open(git_index **index_out, const char *index_path);
+GIT_EXTERN(int) git_index_new(git_index **index_out);
+
+#ifdef GIT_EXPERIMENTAL_SHA256
 
 /**
  * Create an in-memory index object.
  *
- * This index object cannot be read/written to the filesystem,
- * but may be used to perform in-memory index operations.
- *
- * The index must be freed once it's no longer in use.
- *
  * @param index_out the pointer for the new index
+ * @param opts the options for opening the index, or NULL
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_index_new(git_index **index_out);
+GIT_EXTERN(int) git_index_new_ext(
+	git_index **index_out,
+	const git_index_options *opts);
 
 #endif
 

include/git2/odb.h

@@ -62,44 +62,34 @@ typedef struct {
  */
 #define GIT_ODB_OPTIONS_INIT { GIT_ODB_OPTIONS_VERSION }
 
-#ifdef GIT_EXPERIMENTAL_SHA256
-
 /**
  * Create a new object database with no backends.
  *
- * @param[out] odb location to store the database pointer, if opened.
- * @param opts the options for this object database or NULL for defaults
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_odb_new(git_odb **odb, const git_odb_options *opts);
-
-/**
- * Create a new object database and automatically add loose and packed
- * backends.
+ * Before the ODB can be used for read/writing, a custom database
+ * backend must be manually added using `git_odb_add_backend()`
  *
- * @param[out] odb_out location to store the database pointer, if opened.
- *			Set to NULL if the open failed.
- * @param objects_dir path of the backends' "objects" directory.
- * @param opts the options for this object database or NULL for defaults
+ * @note This API only supports SHA1 object databases
+ * @see git_odb_new_ext
+ *
+ * @param[out] odb location to store the database pointer, if opened.
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_odb_open(
-	git_odb **odb_out,
-	const char *objects_dir,
-	const git_odb_options *opts);
+GIT_EXTERN(int) git_odb_new(git_odb **odb);
 
-#else
+#ifdef GIT_EXPERIMENTAL_SHA256
 
 /**
  * Create a new object database with no backends.
  *
- * Before the ODB can be used for read/writing, a custom database
- * backend must be manually added using `git_odb_add_backend()`
- *
  * @param[out] odb location to store the database pointer, if opened.
+ * @param opts the options for this object database or NULL for defaults
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_odb_new(git_odb **odb);
+GIT_EXTERN(int) git_odb_new_ext(
+	git_odb **odb,
+	const git_odb_options *opts);
+
+#endif
 
 /**
  * Create a new object database and automatically add
@@ -112,12 +102,33 @@ GIT_EXTERN(int) git_odb_new(git_odb **odb);
  *		assuming `objects_dir` as the Objects folder which
  *		contains a 'pack/' folder with the corresponding data
  *
+ * @note This API only supports SHA1 object databases
+ * @see git_odb_open_ext
+ *
  * @param[out] odb_out location to store the database pointer, if opened.
  *			Set to NULL if the open failed.
  * @param objects_dir path of the backends' "objects" directory.
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_odb_open(git_odb **odb_out, const char *objects_dir);
+
+#ifdef GIT_EXPERIMENTAL_SHA256
+
+/**
+ * Create a new object database and automatically add loose and packed
+ * backends.
+ *
+ * @param[out] odb_out location to store the database pointer, if opened.
+ *			Set to NULL if the open failed.
+ * @param objects_dir path of the backends' "objects" directory.
+ * @param opts the options for this object database or NULL for defaults
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_open_ext(
+	git_odb **odb_out,
+	const char *objects_dir,
+	const git_odb_options *opts);
+
 #endif
 
 /**

include/git2/sys/repository.h

@@ -20,8 +20,6 @@
  */
 GIT_BEGIN_DECL
 
-#ifdef GIT_EXPERIMENTAL_SHA256
-
 /**
  * The options for creating an repository from scratch.
  *
@@ -64,16 +62,6 @@ GIT_EXTERN(int) git_repository_new_options_init(
 	git_repository_new_options *opts,
 	unsigned int version);
 
-/**
- * Create a new repository with no backends.
- *
- * @param[out] out The blank repository
- * @param opts the options for repository creation, or NULL for defaults
- * @return 0 on success, or an error code
- */
-GIT_EXTERN(int) git_repository_new(git_repository **out, git_repository_new_options *opts);
-#else
-
 /**
  * Create a new repository with neither backends nor config object
  *
@@ -84,11 +72,27 @@ GIT_EXTERN(int) git_repository_new(git_repository **out, git_repository_new_opti
  * can fail to function properly: locations under $GIT_DIR, $GIT_COMMON_DIR,
  * or $GIT_INFO_DIR are impacted.
  *
+ * @note This API only creates SHA1 repositories
+ * @see git_repository_new_ext
+ *
  * @param[out] out The blank repository
  * @return 0 on success, or an error code
  */
 GIT_EXTERN(int) git_repository_new(git_repository **out);
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+
+/**
+ * Create a new repository with no backends.
+ *
+ * @param[out] out The blank repository
+ * @param opts the options for repository creation, or NULL for defaults
+ * @return 0 on success, or an error code
+ */
+GIT_EXTERN(int) git_repository_new_ext(
+	git_repository **out,
+	git_repository_new_options *opts);
+
 #endif
 
 /**