sha256: make sha256 an experimental optional feature

libgit2 can be built with optional, experimental sha256 support. This allows consumers to begin testing and providing feedback for our sha256 support while we continue to develop it, and allows us to make API breaking changes while we iterate on a final sha256 implementation. The results will be `git2-experimental.dll` and installed as `git2-experimental.h` to avoid confusion with a production libgit2.
libgit2 · ethomson · Jul 14, 2022 · Jan 23, 2022 · Jan 17, 2022 · Dec 11, 2021
commit 6c57bac6b18f6a30e1a8c8272a8dc367f202aa88
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -15,6 +15,9 @@ set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${PROJECT_SOURCE_DIR}/cmake")
 # Build options
 #
 
+# Experimental features
+option(EXPERIMENTAL_SHA256     "Enable experimental SHA256 support (for R&D/testing)"  OFF)
+
 # Optional subsystems
 option(BUILD_SHARED_LIBS       "Build Shared Library (OFF for Static)"                  ON)
 option(BUILD_TESTS             "Build Tests using the Clar suite"                       ON)
@@ -107,6 +110,7 @@ include(IdeSplitSources)
 include(FeatureSummary)
 include(EnableWarnings)
 include(DefaultCFlags)
+include(ExperimentalFeatures)
 
 
 #

diff --git a/cmake/ExperimentalFeatures.cmake b/cmake/ExperimentalFeatures.cmake
@@ -0,0 +1,12 @@
+if(EXPERIMENTAL_SHA256)
+	add_feature_info("SHA256 API" ON "experimental SHA256 APIs")
+
+	set(EXPERIMENTAL 1)
+	set(GIT_EXPERIMENTAL_SHA256 1)
+else()
+	add_feature_info("SHA256 API" OFF "experimental SHA256 APIs")
+endif()
+
+if(EXPERIMENTAL)
+	set(LIBGIT2_FILENAME "${LIBGIT2_FILENAME}-experimental")
+endif()
diff --git a/include/git2.h b/include/git2.h
@@ -28,6 +28,7 @@
 #include "git2/diff.h"
 #include "git2/email.h"
 #include "git2/errors.h"
+#include "git2/experimental.h"
 #include "git2/filter.h"
 #include "git2/global.h"
 #include "git2/graph.h"

diff --git a/include/git2/deprecated.h b/include/git2/deprecated.h
@@ -777,6 +777,12 @@ typedef git_trace_cb git_trace_callback;
  */
 /**@{*/
 
+#ifndef GIT_EXPERIMENTAL_SHA256
+# define GIT_OID_RAWSZ    GIT_OID_SHA1_SIZE
+# define GIT_OID_HEXSZ    GIT_OID_SHA1_HEXSIZE
+# define GIT_OID_HEX_ZERO GIT_OID_SHA1_HEXZERO
+#endif
+
 GIT_EXTERN(int) git_oid_iszero(const git_oid *id);
 
 /**@}*/

diff --git a/include/git2/oid.h b/include/git2/oid.h
@@ -9,6 +9,7 @@
 
 #include "common.h"
 #include "types.h"
+#include "experimental.h"
 
 /**
  * @file git2/oid.h
@@ -21,48 +22,91 @@ GIT_BEGIN_DECL
 
 /** The type of object id. */
 typedef enum {
+
+#ifdef GIT_EXPERIMENTAL_SHA256
 	GIT_OID_SHA1 = 1,  /**< SHA1 */
 	GIT_OID_SHA256 = 2 /**< SHA256 */
+#else
+	GIT_OID_SHA1 = 1   /**< SHA1 */
+#endif
+
 } git_oid_t;
 
+/*
+ * SHA1 is currently the only supported object ID type.
+ */
+
 /** SHA1 is currently libgit2's default oid type. */
 #define GIT_OID_DEFAULT         GIT_OID_SHA1
 
-/** Size (in bytes) of a raw/binary oid */
+/** Size (in bytes) of a raw/binary sha1 oid */
 #define GIT_OID_SHA1_SIZE       20
-#define GIT_OID_SHA256_SIZE     32
-#define GIT_OID_MAX_SIZE        GIT_OID_SHA256_SIZE
-
-/** Size (in bytes) of a hex formatted oid */
+/** Size (in bytes) of a hex formatted sha1 oid */
 #define GIT_OID_SHA1_HEXSIZE   (GIT_OID_SHA1_SIZE * 2)
-#define GIT_OID_SHA256_HEXSIZE (GIT_OID_SHA256_SIZE * 2)
-#define GIT_OID_MAX_HEXSIZE     GIT_OID_SHA256_HEXSIZE
+
+/**
+ * The binary representation of the null sha1 object ID.
+ */
+#ifndef GIT_EXPERIMENTAL_SHA256
+# define GIT_OID_SHA1_ZERO   { { 0 } }
+#else
+# define GIT_OID_SHA1_ZERO   { GIT_OID_SHA1, { 0 } }
+#endif
+
+/**
+ * The string representation of the null sha1 object ID.
+ */
+#define GIT_OID_SHA1_HEXZERO   "0000000000000000000000000000000000000000"
+
+/*
+ * Experimental SHA256 support is a breaking change to the API.
+ * This exists for application compatibility testing.
+ */
+
+#ifdef GIT_EXPERIMENTAL_SHA256
+
+/** Size (in bytes) of a raw/binary sha256 oid */
+# define GIT_OID_SHA256_SIZE     32
+/** Size (in bytes) of a hex formatted sha256 oid */
+# define GIT_OID_SHA256_HEXSIZE (GIT_OID_SHA256_SIZE * 2)
+
+/**
+ * The binary representation of the null sha256 object ID.
+ */
+# define GIT_OID_SHA256_ZERO { GIT_OID_SHA256, { 0 } }
+
+/**
+ * The string representation of the null sha256 object ID.
+ */
+# define GIT_OID_SHA256_HEXZERO "0000000000000000000000000000000000000000000000000000000000000000"
+
+#endif
+
+/* Maximum possible object ID size in raw / hex string format. */
+#ifndef GIT_EXPERIMENTAL_SHA256
+# define GIT_OID_MAX_SIZE        GIT_OID_SHA1_SIZE
+# define GIT_OID_MAX_HEXSIZE     GIT_OID_SHA1_HEXSIZE
+#else
+# define GIT_OID_MAX_SIZE        GIT_OID_SHA256_SIZE
+# define GIT_OID_MAX_HEXSIZE     GIT_OID_SHA256_HEXSIZE
+#endif
 
 /** Minimum length (in number of hex characters,
  * i.e. packets of 4 bits) of an oid prefix */
 #define GIT_OID_MINPREFIXLEN 4
 
 /** Unique identity of any object (commit, tree, blob, tag). */
 typedef struct git_oid {
+
+#ifdef GIT_EXPERIMENTAL_SHA256
 	/** type of object id */
 	unsigned char type;
+#endif
 
 	/** raw binary formatted id */
 	unsigned char id[GIT_OID_MAX_SIZE];
 } git_oid;
 
-/**
- * The binary representation of the null object ID.
- */
-#define GIT_OID_SHA1_ZERO   { GIT_OID_SHA1,   { 0 } }
-#define GIT_OID_SHA256_ZERO { GIT_OID_SHA256, { 0 } }
-
-/**
- * The string representation of the null object ID.
- */
-#define GIT_OID_SHA1_HEXZERO   "0000000000000000000000000000000000000000"
-#define GIT_OID_SHA256_HEXZERO "0000000000000000000000000000000000000000000000000000000000000000"
-
 /**
  * Parse a hex formatted object id into a git_oid.
  *

diff --git a/src/cli/CMakeLists.txt b/src/cli/CMakeLists.txt
@@ -1,5 +1,7 @@
 set(CLI_INCLUDES
 	"${libgit2_BINARY_DIR}/src/util"
+	"${libgit2_BINARY_DIR}/include"
+	"${libgit2_BINARY_DIR}/include/git2"
 	"${libgit2_SOURCE_DIR}/src/util"
 	"${libgit2_SOURCE_DIR}/src/cli"
 	"${libgit2_SOURCE_DIR}/include")
@@ -39,6 +41,7 @@ target_link_libraries(git2_cli ${CLI_LIBGIT2_LIBRARY} ${LIBGIT2_SYSTEM_LIBS})
 
 set_target_properties(git2_cli PROPERTIES C_STANDARD 90)
 set_target_properties(git2_cli PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${libgit2_BINARY_DIR})
+set_target_properties(git2_cli PROPERTIES OUTPUT_NAME ${LIBGIT2_FILENAME})
 
 ide_split_sources(git2_cli)
 

diff --git a/src/libgit2/CMakeLists.txt b/src/libgit2/CMakeLists.txt
@@ -9,6 +9,8 @@ include(PkgBuildConfig)
 
 set(LIBGIT2_INCLUDES
 	"${PROJECT_BINARY_DIR}/src/util"
+	"${PROJECT_BINARY_DIR}/include"
+	"${PROJECT_BINARY_DIR}/include/git2"
 	"${PROJECT_SOURCE_DIR}/src/libgit2"
 	"${PROJECT_SOURCE_DIR}/src/util"
 	"${PROJECT_SOURCE_DIR}/include")
@@ -109,7 +111,7 @@ if(SONAME)
 	endif()
 endif()
 
-pkg_build_config(NAME libgit2
+pkg_build_config(NAME "${LIBGIT2_FILENAME}"
 	VERSION ${libgit2_VERSION}
 	DESCRIPTION "The git library, take 2"
 	LIBS_SELF git2
@@ -122,10 +124,26 @@ if(MSVC_IDE)
 	set_source_files_properties(win32/precompiled.c COMPILE_FLAGS "/Ycprecompiled.h")
 endif()
 
+# support experimental features and functionality
+
+configure_file(experimental.h.in "${PROJECT_BINARY_DIR}/include/git2/experimental.h")
+
+# translate filenames in the git2.h so that they match the install directory
+# (allows for side-by-side installs of libgit2 and libgit2-experimental.)
+
+FILE(READ "${PROJECT_SOURCE_DIR}/include/git2.h" LIBGIT2_INCLUDE)
+STRING(REGEX REPLACE "#include \"git2\/" "#include \"${LIBGIT2_FILENAME}/" LIBGIT2_INCLUDE "${LIBGIT2_INCLUDE}")
+FILE(WRITE "${PROJECT_BINARY_DIR}/include/${LIBGIT2_FILENAME}.h" ${LIBGIT2_INCLUDE})
+
 # Install
+
 install(TARGETS libgit2package
 	RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 	LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
 	ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
-install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/git2 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
-install(FILES ${PROJECT_SOURCE_DIR}/include/git2.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/git2/
+        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/${LIBGIT2_FILENAME}")
+install(FILES ${PROJECT_BINARY_DIR}/include/git2/experimental.h
+        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/${LIBGIT2_FILENAME}")
+install(FILES "${PROJECT_BINARY_DIR}/include/${LIBGIT2_FILENAME}.h"
+        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
diff --git a/src/libgit2/diff.c b/src/libgit2/diff.c
@@ -381,7 +381,10 @@ int git_diff_patchid(git_oid *out, git_diff *diff, git_diff_patchid_options *opt
 	if ((error = (flush_hunk(&args.result, &args.ctx))) < 0)
 		goto out;
 
+#ifdef GIT_EXPERIMENTAL_SHA256
 	args.result.type = GIT_OID_SHA1;
+#endif
+
 	git_oid_cpy(out, &args.result);
 
 out:

diff --git a/src/libgit2/experimental.h.in b/src/libgit2/experimental.h.in
@@ -0,0 +1,6 @@
+#ifndef INCLUDE_experimental_h__
+#define INCLUDE_experimental_h__
+
+#cmakedefine GIT_EXPERIMENTAL_SHA256 1
+
+#endif
diff --git a/src/libgit2/indexer.c b/src/libgit2/indexer.c
@@ -444,7 +444,10 @@ static int store_object(git_indexer *idx)
 		git__free(pentry);
 		goto on_error;
 	}
+
+#ifdef GIT_EXPERIMENTAL_SHA256
 	oid.type = GIT_OID_SHA1;
+#endif
 
 	entry_size = idx->off - entry_start;
 	if (entry_start > UINT31_MAX) {

diff --git a/src/libgit2/object.c b/src/libgit2/object.c
@@ -520,7 +520,10 @@ static int git_object__short_id(git_str *out, const git_object *obj)
 		memcpy(&id.id, &obj->cached.oid.id, (len + 1) / 2);
 		if (len & 1)
 			id.id[len / 2] &= 0xf0;
+
+#ifdef GIT_EXPERIMENTAL_SHA256
 		id.type = GIT_OID_SHA1;
+#endif
 
 		error = git_odb_exists_prefix(NULL, odb, &id, len);
 		if (error != GIT_EAMBIGUOUS)
@@ -635,7 +638,7 @@ int git_object__write_oid_header(
 	const char *header,
 	const git_oid *oid)
 {
-	size_t hex_size = git_oid_hexsize(oid->type);
+	size_t hex_size = git_oid_hexsize(git_oid_type(oid));
 	char hex_oid[GIT_OID_MAX_HEXSIZE];
 
 	if (!hex_size) {

diff --git a/src/libgit2/odb.c b/src/libgit2/odb.c
@@ -140,7 +140,10 @@ int git_odb__hashobj(git_oid *id, git_rawobj *obj, git_oid_t oid_type)
 	vec[1].data = obj->data;
 	vec[1].len = obj->len;
 
+#ifdef GIT_EXPERIMENTAL_SHA256
 	id->type = oid_type;
+#endif
+
 	return git_hash_vec(id->id, vec, 2, algorithm);
 }
 
@@ -254,7 +257,10 @@ int git_odb__hashfd(
 	}
 
 	error = git_hash_final(out->id, &ctx);
+
+#ifdef GIT_EXPERIMENTAL_SHA256
 	out->type = oid_type;
+#endif
 
 done:
 	git_hash_ctx_cleanup(&ctx);
@@ -1332,7 +1338,7 @@ int git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id)
 		error = odb_read_1(out, db, id, true);
 
 	if (error == GIT_ENOTFOUND)
-		return git_odb__error_notfound("no match for id", id, git_oid_hexsize(id->type));
+		return git_odb__error_notfound("no match for id", id, git_oid_hexsize(git_oid_type(id)));
 
 	return error;
 }
@@ -1679,7 +1685,10 @@ int git_odb_stream_finalize_write(git_oid *out, git_odb_stream *stream)
 			"stream_finalize_write()");
 
 	git_hash_final(out->id, stream->hash_ctx);
+
+#ifdef GIT_EXPERIMENTAL_SHA256
 	out->type = stream->oid_type;
+#endif
 
 	if (git_odb__freshen(stream->backend->odb, out))
 		return 0;
@@ -1858,8 +1867,8 @@ int git_odb__error_mismatch(const git_oid *expected, const git_oid *actual)
 	char expected_oid[GIT_OID_MAX_HEXSIZE + 1],
 	     actual_oid[GIT_OID_MAX_HEXSIZE + 1];
 
-	git_oid_tostr(expected_oid, git_oid_hexsize(expected->type) + 1, expected);
-	git_oid_tostr(actual_oid, git_oid_hexsize(actual->type) + 1, actual);
+	git_oid_tostr(expected_oid, git_oid_hexsize(git_oid_type(expected)) + 1, expected);
+	git_oid_tostr(actual_oid, git_oid_hexsize(git_oid_type(actual)) + 1, actual);
 
 	git_error_set(GIT_ERROR_ODB, "object hash mismatch - expected %s but got %s",
 		expected_oid, actual_oid);

diff --git a/src/libgit2/odb_loose.c b/src/libgit2/odb_loose.c
@@ -737,7 +737,9 @@ GIT_INLINE(int) filename_to_oid(struct loose_backend *backend, git_oid *oid, con
 		oid->id[1 + i/2] = (unsigned char) v;
 	}
 
+#ifdef GIT_EXPERIMENTAL_SHA256
 	oid->type = backend->options.oid_type;
+#endif
 
 	return 0;
 }