Commit 989abe9be4b200be0c31538834036188e970cf54
2013-02-25T14:03:42
Merge pull request #1362 from schu/packbuilder-nits packbuilder: minor improvements
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
diff --git a/include/git2/pack.h b/include/git2/pack.h
index bc628c5..b8cf77a 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 5137787..84fc4d7 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;