git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2 3/7] hash: document function pointers and wrappers

From
Jeff King <peff@peff.net>
Date
Jul 8, 2026, 03:52 UTC
Message-ID
<20260708035255.GC41620@coredump.intra.peff.net>
In-Reply-To
<20260708035235.GA41491@coredump.intra.peff.net>

We want people to use the git_hash_*() wrappers rather than the bare function pointers in the git_hash_algo struct. Let's document them rather than the bare pointers, and warn people away from the pointers. Coccinelle will eventually force the use of the wrappers, but it's helpful to lead readers in the right direction from the start.

While we're here we can document a few other bits of wisdom I've turned up while working in this area:

  - You have to initialize the destination of a git_hash_clone(). This
    is something we may eventually change for efficiency, but we should
    definitely document the requirement for now.
  - You must eventually finalize or discard a hash, since some backends
    may allocate resources during initialization.
Signed-off-by: Jeff King <peff@peff.net>
---
 hash.h | 43 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 11 deletions(-)
diff --git a/hash.h b/hash.h
index 0a23ef4dfd..121ecf13aa 100644
--- a/hash.h
+++ b/hash.h
@@ -309,22 +309,15 @@ struct git_hash_algo {
 	/* The block size of the hash. */
 	size_t blksz;
 
-	/* The hash initialization function. */
+	/*
+	 * Low-level implementation hooks. Callers should use the git_hash_*
+	 * wrappers below rather than invoking these directly.
+	 */
 	git_hash_init_fn init_fn;
-
-	/* The hash context cloning function. */
 	git_hash_clone_fn clone_fn;
-
-	/* The hash update function. */
 	git_hash_update_fn update_fn;
-
-	/* The hash finalization function. */
 	git_hash_final_fn final_fn;
-
-	/* The hash finalization function for object IDs. */
 	git_hash_final_oid_fn final_oid_fn;
-
-	/* Discard an initialized hash without finalizing. */
 	git_hash_discard_fn discard_fn;
 
 	/* The OID of the empty tree. */
@@ -341,12 +334,40 @@ struct git_hash_algo {
 };
 extern const struct git_hash_algo hash_algos[GIT_HASH_NALGOS];
 
+/*
+ * Prepare an uninitialized hash context for use. You must eventually release
+ * the context with git_hash_final() (or final_oid()) or by calling
+ * git_hash_discard().
+ */
 void git_hash_init(struct git_hash_ctx *ctx, const struct git_hash_algo *algop);
+
+/*
+ * Clone the state of a hash. Both src and dst must have been initialized with
+ * git_hash_init().
+ */
 void git_hash_clone(struct git_hash_ctx *dst, const struct git_hash_ctx *src);
+
+/*
+ * Add more data to an initialized hash context.
+ */
 void git_hash_update(struct git_hash_ctx *ctx, const void *in, size_t len);
+
+/*
+ * Retrieve the final hash value from a context, releasing any resources.
+ */
 void git_hash_final(unsigned char *hash, struct git_hash_ctx *ctx);
+
+/*
+ * Like git_hash_final(), but write the result into an object_id.
+ */
 void git_hash_final_oid(struct object_id *oid, struct git_hash_ctx *ctx);
+
+/*
+ * Discard a hash context without computing the final value, but still
+ * releasing any resources.
+ */
 void git_hash_discard(struct git_hash_ctx *ctx);
+
 const struct git_hash_algo *hash_algo_ptr_by_number(uint32_t algo);
 struct git_hash_ctx *git_hash_alloc(void);
 void git_hash_free(struct git_hash_ctx *ctx);
-- 
2.55.0.459.g1b256877c9
Previous: Jeff KingNext: Jeff King
Message 30 of 35 in “git_hash_*() quality-of-life improvements”
  1. 0/7 git_hash_*() quality-of-life improvementsJeff King, Jul 7, 2026
  2. 1/7 hash: use git_hash_init() consistentlyJeff King, Jul 7, 2026
  3. Junio C HamanoJul 7, 2026
  4. Jeff KingJul 7, 2026
  5. Junio C HamanoJul 7, 2026
  6. Jeff KingJul 7, 2026
  7. brian m. carlsonJul 7, 2026
  8. Jeff KingJul 8, 2026
  9. 2/7 hash: convert remaining direct function callsJeff King, Jul 7, 2026
  10. Junio C HamanoJul 7, 2026
  11. 3/7 hash: document function pointers and wrappersJeff King, Jul 7, 2026
  12. Patrick SteinhardtJul 7, 2026
  13. Jeff KingJul 7, 2026
  14. 4/7 hash: make git_hash_discard() idempotentJeff King, Jul 7, 2026
  15. Junio C HamanoJul 7, 2026
  16. Jeff KingJul 7, 2026
  17. brian m. carlsonJul 7, 2026
  18. Junio C HamanoJul 7, 2026
  19. 5/7 csum-file: use idempotent git_hash_discard()Jeff King, Jul 7, 2026
  20. 6/7 http: use idempotent git_hash_discard()Jeff King, Jul 7, 2026
  21. Junio C HamanoJul 7, 2026
  22. 7/7 hash: check ctx->active flag in all wrapper functionsJeff King, Jul 7, 2026
  23. Patrick SteinhardtJul 7, 2026
  24. Junio C HamanoJul 7, 2026
  25. Jeff KingJul 7, 2026
  26. Patrick SteinhardtJul 7, 2026
  27. 0/7 git_hash_*() quality-of-life improvementsJeff King, Jul 8, 2026
  28. 1/7 hash: use git_hash_init() consistentlyJeff King, Jul 8, 2026
  29. 2/7 hash: convert remaining direct function callsJeff King, Jul 8, 2026
  30. 3/7 hash: document function pointers and wrappersJeff King, Jul 8, 2026
  31. 4/7 hash: make git_hash_discard() idempotentJeff King, Jul 8, 2026
  32. 5/7 csum-file: use idempotent git_hash_discard()Jeff King, Jul 8, 2026
  33. 6/7 http: use idempotent git_hash_discard()Jeff King, Jul 8, 2026
  34. 7/7 hash: check ctx->active flag in all wrapper functionsJeff King, Jul 8, 2026
  35. Patrick SteinhardtJul 8, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.