diff --git a/include/git2/pack.h b/include/git2/pack.h
index bc628c56a..b8cf77a49 100644
--- a/include/git2/pack.h
+++ b/include/git2/pack.h
@@ -13,7 +13,33 @@
 /**
  * @file git2/pack.h
  * @brief Git pack management routines
- * @defgroup git_pack Git pack management routines
+ *
+ * Packing objects
+ * ---------------
+ *
+ * Creation of packfiles requires two steps:
+ *
+ * - First, insert all the objects you want to put into the packfile
+ *   using `git_packbuilder_insert` and `git_packbuilder_insert_tree`.
+ *   It's important to add the objects in recency order ("in the order
+ *   that they are 'reachable' from head").
+ *
+ *   "ANY order will give you a working pack, ... [but it is] the thing
+ *   that gives packs good locality. It keeps the objects close to the
+ *   head (whether they are old or new, but they are _reachable_ from the
+ *   head) at the head of the pack. So packs actually have absolutely
+ *   _wonderful_ IO patterns." - Linus Torvalds
+ *   git.git/Documentation/technical/pack-heuristics.txt
+ *
+ * - Second, use `git_packbuilder_write` or `git_packbuilder_foreach` to
+ *   write the resulting packfile.
+ *
+ *   libgit2 will take care of the delta ordering and generation.
+ *   `git_packbuilder_set_threads` can be used to adjust the number of
+ *   threads used for the process.
+ *
+ * See tests-clar/pack/packbuilder.c for an example.
+ *
  * @ingroup Git
  * @{
  */
diff --git a/tests-clar/pack/packbuilder.c b/tests-clar/pack/packbuilder.c
index 513778781..84fc4d7bd 100644
--- a/tests-clar/pack/packbuilder.c
+++ b/tests-clar/pack/packbuilder.c
@@ -1,4 +1,6 @@
 #include "clar_libgit2.h"
+#include "fileops.h"
+#include "hash.h"
 #include "iterator.h"
 #include "vector.h"
 #include "posix.h"
@@ -76,6 +78,10 @@ static void seed_packbuilder(void)
 void test_pack_packbuilder__create_pack(void)
 {
 	git_transfer_progress stats;
+	git_buf buf = GIT_BUF_INIT;
+	git_hash_ctx ctx;
+	git_oid hash;
+	char hex[41]; hex[40] = '\0';
 
 	seed_packbuilder();
 	cl_git_pass(git_packbuilder_write(_packbuilder, "testpack.pack"));
@@ -83,6 +89,32 @@ void test_pack_packbuilder__create_pack(void)
 	cl_git_pass(git_indexer_new(&_indexer, "testpack.pack"));
 	cl_git_pass(git_indexer_run(_indexer, &stats));
 	cl_git_pass(git_indexer_write(_indexer));
+
+	/*
+	 * By default, packfiles are created with only one thread.
+	 * Therefore we can predict the object ordering and make sure
+	 * we create exactly the same pack as git.git does when *not*
+	 * reusing existing deltas (as libgit2).
+	 *
+	 * $ cd tests-clar/resources/testrepo.git
+	 * $ git rev-list --objects HEAD | \
+	 * 	git pack-objects -q --no-reuse-delta --threads=1 pack
+	 * $ sha1sum git-80e61eb315239ef3c53033e37fee43b744d57122.pack
+	 * 5d410bdf97cf896f9007681b92868471d636954b
+	 *
+	 */
+
+	cl_git_pass(git_futils_readbuffer(&buf, "testpack.pack"));
+
+	cl_git_pass(git_hash_init(&ctx));
+	cl_git_pass(git_hash_update(&ctx, buf.ptr, buf.size));
+	cl_git_pass(git_hash_final(&hash, &ctx));
+
+	git_buf_free(&buf);
+
+	git_oid_fmt(hex, &hash);
+
+	cl_assert_equal_s(hex, "5d410bdf97cf896f9007681b92868471d636954b");
 }
 
 static git_transfer_progress stats;