]>
Commit | Line | Data |
---|---|---|
0a32dca5 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
0a32dca5 MS |
3 | * |
4 | * This file is part of libgit2, distributed under the GNU GPL v2 with | |
5 | * a Linking Exception. For full terms see the included COPYING file. | |
6 | */ | |
7 | #ifndef INCLUDE_git_pack_h__ | |
8 | #define INCLUDE_git_pack_h__ | |
9 | ||
10 | #include "common.h" | |
11 | #include "oid.h" | |
22a2d3d5 | 12 | #include "indexer.h" |
0a32dca5 MS |
13 | |
14 | /** | |
15 | * @file git2/pack.h | |
16 | * @brief Git pack management routines | |
fcc265fe MS |
17 | * |
18 | * Packing objects | |
19 | * --------------- | |
20 | * | |
21 | * Creation of packfiles requires two steps: | |
22 | * | |
23 | * - First, insert all the objects you want to put into the packfile | |
24 | * using `git_packbuilder_insert` and `git_packbuilder_insert_tree`. | |
25 | * It's important to add the objects in recency order ("in the order | |
26 | * that they are 'reachable' from head"). | |
27 | * | |
28 | * "ANY order will give you a working pack, ... [but it is] the thing | |
29 | * that gives packs good locality. It keeps the objects close to the | |
30 | * head (whether they are old or new, but they are _reachable_ from the | |
31 | * head) at the head of the pack. So packs actually have absolutely | |
32 | * _wonderful_ IO patterns." - Linus Torvalds | |
33 | * git.git/Documentation/technical/pack-heuristics.txt | |
34 | * | |
35 | * - Second, use `git_packbuilder_write` or `git_packbuilder_foreach` to | |
36 | * write the resulting packfile. | |
37 | * | |
38 | * libgit2 will take care of the delta ordering and generation. | |
39 | * `git_packbuilder_set_threads` can be used to adjust the number of | |
40 | * threads used for the process. | |
41 | * | |
83e1efbf | 42 | * See tests/pack/packbuilder.c for an example. |
fcc265fe | 43 | * |
0a32dca5 MS |
44 | * @ingroup Git |
45 | * @{ | |
46 | */ | |
47 | GIT_BEGIN_DECL | |
48 | ||
b176eded JM |
49 | /** |
50 | * Stages that are reported by the packbuilder progress callback. | |
51 | */ | |
52 | typedef enum { | |
53 | GIT_PACKBUILDER_ADDING_OBJECTS = 0, | |
e579e0f7 | 54 | GIT_PACKBUILDER_DELTAFICATION = 1 |
b176eded | 55 | } git_packbuilder_stage_t; |
7697e541 | 56 | |
0a32dca5 MS |
57 | /** |
58 | * Initialize a new packbuilder | |
59 | * | |
60 | * @param out The new packbuilder object | |
61 | * @param repo The repository | |
62 | * | |
63 | * @return 0 or an error code | |
64 | */ | |
65 | GIT_EXTERN(int) git_packbuilder_new(git_packbuilder **out, git_repository *repo); | |
66 | ||
67 | /** | |
68 | * Set number of threads to spawn | |
69 | * | |
70 | * By default, libgit2 won't spawn any threads at all; | |
71 | * when set to 0, libgit2 will autodetect the number of | |
72 | * CPUs. | |
73 | * | |
74 | * @param pb The packbuilder | |
75 | * @param n Number of threads to spawn | |
2508cc66 | 76 | * @return number of actual threads to be used |
0a32dca5 | 77 | */ |
2508cc66 | 78 | GIT_EXTERN(unsigned int) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n); |
0a32dca5 MS |
79 | |
80 | /** | |
81 | * Insert a single object | |
82 | * | |
83 | * For an optimal pack it's mandatory to insert objects in recency order, | |
84 | * commits followed by trees and blobs. | |
85 | * | |
86 | * @param pb The packbuilder | |
2508cc66 BS |
87 | * @param id The oid of the commit |
88 | * @param name The name; might be NULL | |
0a32dca5 MS |
89 | * |
90 | * @return 0 or an error code | |
91 | */ | |
2508cc66 | 92 | GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *id, const char *name); |
0a32dca5 MS |
93 | |
94 | /** | |
95 | * Insert a root tree object | |
96 | * | |
97 | * This will add the tree as well as all referenced trees and blobs. | |
98 | * | |
99 | * @param pb The packbuilder | |
2508cc66 | 100 | * @param id The oid of the root tree |
0a32dca5 MS |
101 | * |
102 | * @return 0 or an error code | |
103 | */ | |
2508cc66 | 104 | GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *id); |
0a32dca5 | 105 | |
f0e37a8b X |
106 | /** |
107 | * Insert a commit object | |
1fed6b07 | 108 | * |
f0e37a8b | 109 | * This will add a commit as well as the completed referenced tree. |
1fed6b07 | 110 | * |
f0e37a8b X |
111 | * @param pb The packbuilder |
112 | * @param id The oid of the commit | |
1fed6b07 | 113 | * |
f0e37a8b X |
114 | * @return 0 or an error code |
115 | */ | |
116 | GIT_EXTERN(int) git_packbuilder_insert_commit(git_packbuilder *pb, const git_oid *id); | |
117 | ||
04a36fef CMN |
118 | /** |
119 | * Insert objects as given by the walk | |
120 | * | |
121 | * Those commits and all objects they reference will be inserted into | |
122 | * the packbuilder. | |
123 | * | |
124 | * @param pb the packbuilder | |
125 | * @param walk the revwalk to use to fill the packbuilder | |
126 | * | |
127 | * @return 0 or an error code | |
128 | */ | |
129 | GIT_EXTERN(int) git_packbuilder_insert_walk(git_packbuilder *pb, git_revwalk *walk); | |
130 | ||
a61fa4c0 CMN |
131 | /** |
132 | * Recursively insert an object and its referenced objects | |
133 | * | |
134 | * Insert the object as well as any object it references. | |
135 | * | |
136 | * @param pb the packbuilder | |
137 | * @param id the id of the root object to insert | |
138 | * @param name optional name for the object | |
139 | * @return 0 or an error code | |
140 | */ | |
141 | GIT_EXTERN(int) git_packbuilder_insert_recur(git_packbuilder *pb, const git_oid *id, const char *name); | |
142 | ||
6105d597 VM |
143 | /** |
144 | * Write the contents of the packfile to an in-memory buffer | |
145 | * | |
146 | * The contents of the buffer will become a valid packfile, even though there | |
147 | * will be no attached index | |
148 | * | |
149 | * @param buf Buffer where to write the packfile | |
150 | * @param pb The packbuilder | |
e579e0f7 | 151 | * @return 0 or an error code |
6105d597 VM |
152 | */ |
153 | GIT_EXTERN(int) git_packbuilder_write_buf(git_buf *buf, git_packbuilder *pb); | |
154 | ||
0a32dca5 | 155 | /** |
563c19a9 | 156 | * Write the new pack and corresponding index file to path. |
0a32dca5 MS |
157 | * |
158 | * @param pb The packbuilder | |
22a2d3d5 | 159 | * @param path Path to the directory where the packfile and index should be stored, or NULL for default location |
1e60e5f4 | 160 | * @param mode permissions to use creating a packfile or 0 for defaults |
563c19a9 | 161 | * @param progress_cb function to call with progress information from the indexer (optional) |
e1967164 | 162 | * @param progress_cb_payload payload for the progress callback (optional) |
0a32dca5 MS |
163 | * |
164 | * @return 0 or an error code | |
165 | */ | |
563c19a9 MS |
166 | GIT_EXTERN(int) git_packbuilder_write( |
167 | git_packbuilder *pb, | |
168 | const char *path, | |
1e60e5f4 | 169 | unsigned int mode, |
22a2d3d5 | 170 | git_indexer_progress_cb progress_cb, |
563c19a9 | 171 | void *progress_cb_payload); |
0a32dca5 | 172 | |
e579e0f7 | 173 | #ifndef GIT_DEPRECATE_HARD |
cc2447da | 174 | /** |
e579e0f7 MB |
175 | * Get the packfile's hash |
176 | * | |
177 | * A packfile's name is derived from the sorted hashing of all object | |
178 | * names. This is only correct after the packfile has been written. | |
179 | * | |
180 | * @deprecated use git_packbuilder_name | |
181 | * @param pb The packbuilder object | |
182 | * @return 0 or an error code | |
183 | */ | |
cc2447da | 184 | GIT_EXTERN(const git_oid *) git_packbuilder_hash(git_packbuilder *pb); |
e579e0f7 MB |
185 | #endif |
186 | ||
187 | /** | |
188 | * Get the unique name for the resulting packfile. | |
189 | * | |
190 | * The packfile's name is derived from the packfile's content. | |
191 | * This is only correct after the packfile has been written. | |
192 | * | |
193 | * @param pb the packbuilder instance | |
194 | * @return a NUL terminated string for the packfile name | |
195 | */ | |
196 | GIT_EXTERN(const char *) git_packbuilder_name(git_packbuilder *pb); | |
cc2447da | 197 | |
22a2d3d5 UG |
198 | /** |
199 | * Callback used to iterate over packed objects | |
200 | * | |
201 | * @see git_packbuilder_foreach | |
202 | * | |
203 | * @param buf A pointer to the object's data | |
204 | * @param size The size of the underlying object | |
205 | * @param payload Payload passed to git_packbuilder_foreach | |
206 | * @return non-zero to terminate the iteration | |
207 | */ | |
ac3d33df | 208 | typedef int GIT_CALLBACK(git_packbuilder_foreach_cb)(void *buf, size_t size, void *payload); |
7697e541 | 209 | |
3dfed9cb CMN |
210 | /** |
211 | * Create the new pack and pass each object to the callback | |
212 | * | |
213 | * @param pb the packbuilder | |
214 | * @param cb the callback to call with each packed object's buffer | |
2508cc66 | 215 | * @param payload the callback's data |
3dfed9cb CMN |
216 | * @return 0 or an error code |
217 | */ | |
2508cc66 | 218 | GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, git_packbuilder_foreach_cb cb, void *payload); |
3dfed9cb | 219 | |
b4b935d8 CMN |
220 | /** |
221 | * Get the total number of objects the packbuilder will write out | |
222 | * | |
223 | * @param pb the packbuilder | |
c05a55b0 | 224 | * @return the number of objects in the packfile |
b4b935d8 | 225 | */ |
60e15ecd | 226 | GIT_EXTERN(size_t) git_packbuilder_object_count(git_packbuilder *pb); |
b4b935d8 CMN |
227 | |
228 | /** | |
229 | * Get the number of objects the packbuilder has already written out | |
230 | * | |
231 | * @param pb the packbuilder | |
c05a55b0 | 232 | * @return the number of objects which have already been written |
b4b935d8 | 233 | */ |
60e15ecd | 234 | GIT_EXTERN(size_t) git_packbuilder_written(git_packbuilder *pb); |
b4b935d8 | 235 | |
b176eded | 236 | /** Packbuilder progress notification function */ |
ac3d33df | 237 | typedef int GIT_CALLBACK(git_packbuilder_progress)( |
b176eded | 238 | int stage, |
60e15ecd ET |
239 | uint32_t current, |
240 | uint32_t total, | |
b176eded JM |
241 | void *payload); |
242 | ||
243 | /** | |
244 | * Set the callbacks for a packbuilder | |
245 | * | |
246 | * @param pb The packbuilder object | |
247 | * @param progress_cb Function to call with progress information during | |
248 | * pack building. Be aware that this is called inline with pack building | |
249 | * operations, so performance may be affected. | |
250 | * @param progress_cb_payload Payload for progress callback. | |
251 | * @return 0 or an error code | |
252 | */ | |
253 | GIT_EXTERN(int) git_packbuilder_set_callbacks( | |
254 | git_packbuilder *pb, | |
255 | git_packbuilder_progress progress_cb, | |
256 | void *progress_cb_payload); | |
257 | ||
0a32dca5 MS |
258 | /** |
259 | * Free the packbuilder and all associated data | |
260 | * | |
261 | * @param pb The packbuilder | |
262 | */ | |
263 | GIT_EXTERN(void) git_packbuilder_free(git_packbuilder *pb); | |
264 | ||
265 | /** @} */ | |
266 | GIT_END_DECL | |
267 | #endif |