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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
/*
* Copyright (C) the libgit2 contributors. All rights reserved.
*
* This file is part of libgit2, distributed under the GNU GPL v2 with
* a Linking Exception. For full terms see the included COPYING file.
*/
#ifndef INCLUDE_git_pack_h__
#define INCLUDE_git_pack_h__
#include "common.h"
#include "oid.h"
/**
* @file git2/pack.h
* @brief 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/pack/packbuilder.c for an example.
*
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* Stages that are reported by the packbuilder progress callback.
*/
typedef enum {
GIT_PACKBUILDER_ADDING_OBJECTS = 0,
GIT_PACKBUILDER_DELTAFICATION = 1,
} git_packbuilder_stage_t;
/**
* Initialize a new packbuilder
*
* @param out The new packbuilder object
* @param repo The repository
*
* @return 0 or an error code
*/
GIT_EXTERN(int) git_packbuilder_new(git_packbuilder **out, git_repository *repo);
/**
* Set number of threads to spawn
*
* By default, libgit2 won't spawn any threads at all;
* when set to 0, libgit2 will autodetect the number of
* CPUs.
*
* @param pb The packbuilder
* @param n Number of threads to spawn
* @return number of actual threads to be used
*/
GIT_EXTERN(unsigned int) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n);
/**
* Insert a single object
*
* For an optimal pack it's mandatory to insert objects in recency order,
* commits followed by trees and blobs.
*
* @param pb The packbuilder
* @param id The oid of the commit
* @param name The name; might be NULL
*
* @return 0 or an error code
*/
GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *id, const char *name);
/**
* Insert a root tree object
*
* This will add the tree as well as all referenced trees and blobs.
*
* @param pb The packbuilder
* @param id The oid of the root tree
*
* @return 0 or an error code
*/
GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *id);
/**
* Insert a commit object
*
* This will add a commit as well as the completed referenced tree.
*
* @param pb The packbuilder
* @param id The oid of the commit
*
* @return 0 or an error code
*/
GIT_EXTERN(int) git_packbuilder_insert_commit(git_packbuilder *pb, const git_oid *id);
/**
* Write the new pack and corresponding index file to path.
*
* @param pb The packbuilder
* @param path to the directory where the packfile and index should be stored
* @param mode permissions to use creating a packfile or 0 for defaults
* @param progress_cb function to call with progress information from the indexer (optional)
* @param progress_cb_payload payload for the progress callback (optional)
*
* @return 0 or an error code
*/
GIT_EXTERN(int) git_packbuilder_write(
git_packbuilder *pb,
const char *path,
unsigned int mode,
git_transfer_progress_callback progress_cb,
void *progress_cb_payload);
/**
* Get the packfile's hash
*
* A packfile's name is derived from the sorted hashing of all object
* names. This is only correct after the packfile has been written.
*
* @param pb The packbuilder object
*/
GIT_EXTERN(const git_oid *) git_packbuilder_hash(git_packbuilder *pb);
typedef int (*git_packbuilder_foreach_cb)(void *buf, size_t size, void *payload);
/**
* Create the new pack and pass each object to the callback
*
* @param pb the packbuilder
* @param cb the callback to call with each packed object's buffer
* @param payload the callback's data
* @return 0 or an error code
*/
GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, git_packbuilder_foreach_cb cb, void *payload);
/**
* Get the total number of objects the packbuilder will write out
*
* @param pb the packbuilder
* @return the number of objects in the packfile
*/
GIT_EXTERN(uint32_t) git_packbuilder_object_count(git_packbuilder *pb);
/**
* Get the number of objects the packbuilder has already written out
*
* @param pb the packbuilder
* @return the number of objects which have already been written
*/
GIT_EXTERN(uint32_t) git_packbuilder_written(git_packbuilder *pb);
/** Packbuilder progress notification function */
typedef int (*git_packbuilder_progress)(
int stage,
unsigned int current,
unsigned int total,
void *payload);
/**
* Set the callbacks for a packbuilder
*
* @param pb The packbuilder object
* @param progress_cb Function to call with progress information during
* pack building. Be aware that this is called inline with pack building
* operations, so performance may be affected.
* @param progress_cb_payload Payload for progress callback.
* @return 0 or an error code
*/
GIT_EXTERN(int) git_packbuilder_set_callbacks(
git_packbuilder *pb,
git_packbuilder_progress progress_cb,
void *progress_cb_payload);
/**
* Free the packbuilder and all associated data
*
* @param pb The packbuilder
*/
GIT_EXTERN(void) git_packbuilder_free(git_packbuilder *pb);
/** @} */
GIT_END_DECL
#endif
|
