FilesExpand file tree

main

/

pack.h

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

279 lines (256 loc) · 8.04 KB

main

/

pack.h

Copy path

Top

File metadata and controls

• Code
• Blame

279 lines (256 loc) · 8.04 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

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

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

/*

* 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"

#include "indexer.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);

/**

* Insert objects as given by the walk

*

* Those commits and all objects they reference will be inserted into

* the packbuilder.

*

* @param pb the packbuilder

* @param walk the revwalk to use to fill the packbuilder

*

* @return 0 or an error code

*/

GIT_EXTERN(int) git_packbuilder_insert_walk(git_packbuilder *pb, git_revwalk *walk);

/**

* Recursively insert an object and its referenced objects

*

* Insert the object as well as any object it references.

*

* @param pb the packbuilder

* @param id the id of the root object to insert

* @param name optional name for the object

* @return 0 or an error code

*/

GIT_EXTERN(int) git_packbuilder_insert_recur(git_packbuilder *pb, const git_oid *id, const char *name);

/**

* Write the contents of the packfile to an in-memory buffer

*

* The contents of the buffer will become a valid packfile, even though there

* will be no attached index

*

* @param buf Buffer where to write the packfile

* @param pb The packbuilder

* @return 0 or an error code

*/

GIT_EXTERN(int) git_packbuilder_write_buf(git_buf *buf, git_packbuilder *pb);

/**

* Write the new pack and corresponding index file to path.

*

* @param pb The packbuilder

* @param path Path to the directory where the packfile and index should be stored, or NULL for default location

* @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_indexer_progress_cb progress_cb,

void *progress_cb_payload);

#ifndef GIT_DEPRECATE_HARD

/**

* 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.

*

* @deprecated use git_packbuilder_name

* @param pb The packbuilder object

* @return 0 or an error code

*/

GIT_EXTERN(const git_oid *) git_packbuilder_hash(git_packbuilder *pb);

#endif

/**

* Get the unique name for the resulting packfile.

*

* The packfile's name is derived from the packfile's content.

* This is only correct after the packfile has been written.

*

* @param pb the packbuilder instance

* @return a NUL terminated string for the packfile name

*/

GIT_EXTERN(const char *) git_packbuilder_name(git_packbuilder *pb);

/**

* Callback used to iterate over packed objects

*

* @see git_packbuilder_foreach

*

* @param buf A pointer to the object's data

* @param size The size of the underlying object

* @param payload Payload passed to git_packbuilder_foreach

* @return non-zero to terminate the iteration

*/

typedef int GIT_CALLBACK(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(size_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(size_t) git_packbuilder_written(git_packbuilder *pb);

/**

* Packbuilder progress notification function.

*

* @param stage the stage of the packbuilder

* @param current the current object

* @param total the total number of objects

* @param payload the callback payload

* @return 0 on success or an error code

*/

typedef int GIT_CALLBACK(git_packbuilder_progress)(

int stage,

uint32_t current,

uint32_t 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.

* When progress_cb returns an error, the pack building process will be

* aborted and the error will be returned from the invoked function.

* `pb` must then be freed.

* @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