From fcc265fef814c0428fb6300e7f89d4ee99311ee7 Mon Sep 17 00:00:00 2001 From: Michael Schubert Date: Sun, 17 Feb 2013 16:52:26 +0100 Subject: pack.h: improve docs on how to create a packfile --- include/git2/pack.h | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) (limited to 'include/git2/pack.h') 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 * @{ */ -- cgit v1.2.1