/*

[0] Fix | Delete

* Copyright (C) the libgit2 contributors. All rights reserved.

[1] Fix | Delete

*

[2] Fix | Delete

* This file is part of libgit2, distributed under the GNU GPL v2 with

[3] Fix | Delete

* a Linking Exception. For full terms see the included COPYING file.

[4] Fix | Delete

*/

[5] Fix | Delete

#ifndef INCLUDE_git_pack_h__

[6] Fix | Delete

#define INCLUDE_git_pack_h__

[7] Fix | Delete

[8] Fix | Delete

#include "common.h"

[9] Fix | Delete

#include "oid.h"

[10] Fix | Delete

#include "indexer.h"

[11] Fix | Delete

[12] Fix | Delete

/**

[13] Fix | Delete

* @file git2/pack.h

[14] Fix | Delete

* @brief Git pack management routines

[15] Fix | Delete

*

[16] Fix | Delete

* Packing objects

[17] Fix | Delete

* ---------------

[18] Fix | Delete

*

[19] Fix | Delete

* Creation of packfiles requires two steps:

[20] Fix | Delete

*

[21] Fix | Delete

* - First, insert all the objects you want to put into the packfile

[22] Fix | Delete

* using `git_packbuilder_insert` and `git_packbuilder_insert_tree`.

[23] Fix | Delete

* It's important to add the objects in recency order ("in the order

[24] Fix | Delete

* that they are 'reachable' from head").

[25] Fix | Delete

*

[26] Fix | Delete

* "ANY order will give you a working pack, ... [but it is] the thing

[27] Fix | Delete

* that gives packs good locality. It keeps the objects close to the

[28] Fix | Delete

* head (whether they are old or new, but they are _reachable_ from the

[29] Fix | Delete

* head) at the head of the pack. So packs actually have absolutely

[30] Fix | Delete

* _wonderful_ IO patterns." - Linus Torvalds

[31] Fix | Delete

* git.git/Documentation/technical/pack-heuristics.txt

[32] Fix | Delete

*

[33] Fix | Delete

* - Second, use `git_packbuilder_write` or `git_packbuilder_foreach` to

[34] Fix | Delete

* write the resulting packfile.

[35] Fix | Delete

*

[36] Fix | Delete

* libgit2 will take care of the delta ordering and generation.

[37] Fix | Delete

* `git_packbuilder_set_threads` can be used to adjust the number of

[38] Fix | Delete

* threads used for the process.

[39] Fix | Delete

*

[40] Fix | Delete

* See tests/pack/packbuilder.c for an example.

[41] Fix | Delete

*

[42] Fix | Delete

* @ingroup Git

[43] Fix | Delete

* @{

[44] Fix | Delete

*/

[45] Fix | Delete

GIT_BEGIN_DECL

[46] Fix | Delete

[47] Fix | Delete

/**

[48] Fix | Delete

* Stages that are reported by the packbuilder progress callback.

[49] Fix | Delete

*/

[50] Fix | Delete

typedef enum {

[51] Fix | Delete

GIT_PACKBUILDER_ADDING_OBJECTS = 0,

[52] Fix | Delete

GIT_PACKBUILDER_DELTAFICATION = 1,

[53] Fix | Delete

} git_packbuilder_stage_t;

[54] Fix | Delete

[55] Fix | Delete

/**

[56] Fix | Delete

* Initialize a new packbuilder

[57] Fix | Delete

*

[58] Fix | Delete

* @param out The new packbuilder object

[59] Fix | Delete

* @param repo The repository

[60] Fix | Delete

*

[61] Fix | Delete

* @return 0 or an error code

[62] Fix | Delete

*/

[63] Fix | Delete

GIT_EXTERN(int) git_packbuilder_new(git_packbuilder **out, git_repository *repo);

[64] Fix | Delete

[65] Fix | Delete

/**

[66] Fix | Delete

* Set number of threads to spawn

[67] Fix | Delete

*

[68] Fix | Delete

* By default, libgit2 won't spawn any threads at all;

[69] Fix | Delete

* when set to 0, libgit2 will autodetect the number of

[70] Fix | Delete

* CPUs.

[71] Fix | Delete

*

[72] Fix | Delete

* @param pb The packbuilder

[73] Fix | Delete

* @param n Number of threads to spawn

[74] Fix | Delete

* @return number of actual threads to be used

[75] Fix | Delete

*/

[76] Fix | Delete

GIT_EXTERN(unsigned int) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n);

[77] Fix | Delete

[78] Fix | Delete

/**

[79] Fix | Delete

* Insert a single object

[80] Fix | Delete

*

[81] Fix | Delete

* For an optimal pack it's mandatory to insert objects in recency order,

[82] Fix | Delete

* commits followed by trees and blobs.

[83] Fix | Delete

*

[84] Fix | Delete

* @param pb The packbuilder

[85] Fix | Delete

* @param id The oid of the commit

[86] Fix | Delete

* @param name The name; might be NULL

[87] Fix | Delete

*

[88] Fix | Delete

* @return 0 or an error code

[89] Fix | Delete

*/

[90] Fix | Delete

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

[91] Fix | Delete

[92] Fix | Delete

/**

[93] Fix | Delete

* Insert a root tree object

[94] Fix | Delete

*

[95] Fix | Delete

* This will add the tree as well as all referenced trees and blobs.

[96] Fix | Delete

*

[97] Fix | Delete

* @param pb The packbuilder

[98] Fix | Delete

* @param id The oid of the root tree

[99] Fix | Delete

*

[100] Fix | Delete

* @return 0 or an error code

[101] Fix | Delete

*/

[102] Fix | Delete

GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *id);

[103] Fix | Delete

[104] Fix | Delete

/**

[105] Fix | Delete

* Insert a commit object

[106] Fix | Delete

*

[107] Fix | Delete

* This will add a commit as well as the completed referenced tree.

[108] Fix | Delete

*

[109] Fix | Delete

* @param pb The packbuilder

[110] Fix | Delete

* @param id The oid of the commit

[111] Fix | Delete

*

[112] Fix | Delete

* @return 0 or an error code

[113] Fix | Delete

*/

[114] Fix | Delete

GIT_EXTERN(int) git_packbuilder_insert_commit(git_packbuilder *pb, const git_oid *id);

[115] Fix | Delete

[116] Fix | Delete

/**

[117] Fix | Delete

* Insert objects as given by the walk

[118] Fix | Delete

*

[119] Fix | Delete

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

[120] Fix | Delete

* the packbuilder.

[121] Fix | Delete

*

[122] Fix | Delete

* @param pb the packbuilder

[123] Fix | Delete

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

[124] Fix | Delete

*

[125] Fix | Delete

* @return 0 or an error code

[126] Fix | Delete

*/

[127] Fix | Delete

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

[128] Fix | Delete

[129] Fix | Delete

/**

[130] Fix | Delete

* Recursively insert an object and its referenced objects

[131] Fix | Delete

*

[132] Fix | Delete

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

[133] Fix | Delete

*

[134] Fix | Delete

* @param pb the packbuilder

[135] Fix | Delete

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

[136] Fix | Delete

* @param name optional name for the object

[137] Fix | Delete

* @return 0 or an error code

[138] Fix | Delete

*/

[139] Fix | Delete

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

[140] Fix | Delete

[141] Fix | Delete

/**

[142] Fix | Delete

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

[143] Fix | Delete

*

[144] Fix | Delete

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

[145] Fix | Delete

* will be no attached index

[146] Fix | Delete

*

[147] Fix | Delete

* @param buf Buffer where to write the packfile

[148] Fix | Delete

* @param pb The packbuilder

[149] Fix | Delete

*/

[150] Fix | Delete

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

[151] Fix | Delete

[152] Fix | Delete

/**

[153] Fix | Delete

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

[154] Fix | Delete

*

[155] Fix | Delete

* @param pb The packbuilder

[156] Fix | Delete

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

[157] Fix | Delete

* @param mode permissions to use creating a packfile or 0 for defaults

[158] Fix | Delete

* @param progress_cb function to call with progress information from the indexer (optional)

[159] Fix | Delete

* @param progress_cb_payload payload for the progress callback (optional)

[160] Fix | Delete

*

[161] Fix | Delete

* @return 0 or an error code

[162] Fix | Delete

*/

[163] Fix | Delete

GIT_EXTERN(int) git_packbuilder_write(

[164] Fix | Delete

git_packbuilder *pb,

[165] Fix | Delete

const char *path,

[166] Fix | Delete

unsigned int mode,

[167] Fix | Delete

git_indexer_progress_cb progress_cb,

[168] Fix | Delete

void *progress_cb_payload);

[169] Fix | Delete

[170] Fix | Delete

/**

[171] Fix | Delete

* Get the packfile's hash

[172] Fix | Delete

*

[173] Fix | Delete

* A packfile's name is derived from the sorted hashing of all object

[174] Fix | Delete

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

[175] Fix | Delete

*

[176] Fix | Delete

* @param pb The packbuilder object

[177] Fix | Delete

*/

[178] Fix | Delete

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

[179] Fix | Delete

[180] Fix | Delete

/**

[181] Fix | Delete

* Callback used to iterate over packed objects

[182] Fix | Delete

*

[183] Fix | Delete

* @see git_packbuilder_foreach

[184] Fix | Delete

*

[185] Fix | Delete

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

[186] Fix | Delete

* @param size The size of the underlying object

[187] Fix | Delete

* @param payload Payload passed to git_packbuilder_foreach

[188] Fix | Delete

* @return non-zero to terminate the iteration

[189] Fix | Delete

*/

[190] Fix | Delete

typedef int GIT_CALLBACK(git_packbuilder_foreach_cb)(void *buf, size_t size, void *payload);

[191] Fix | Delete

[192] Fix | Delete

/**

[193] Fix | Delete

* Create the new pack and pass each object to the callback

[194] Fix | Delete

*

[195] Fix | Delete

* @param pb the packbuilder

[196] Fix | Delete

* @param cb the callback to call with each packed object's buffer

[197] Fix | Delete

* @param payload the callback's data

[198] Fix | Delete

* @return 0 or an error code

[199] Fix | Delete

*/

[200] Fix | Delete

GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, git_packbuilder_foreach_cb cb, void *payload);

[201] Fix | Delete

[202] Fix | Delete

/**

[203] Fix | Delete

* Get the total number of objects the packbuilder will write out

[204] Fix | Delete

*

[205] Fix | Delete

* @param pb the packbuilder

[206] Fix | Delete

* @return the number of objects in the packfile

[207] Fix | Delete

*/

[208] Fix | Delete

GIT_EXTERN(size_t) git_packbuilder_object_count(git_packbuilder *pb);

[209] Fix | Delete

[210] Fix | Delete

/**

[211] Fix | Delete

* Get the number of objects the packbuilder has already written out

[212] Fix | Delete

*

[213] Fix | Delete

* @param pb the packbuilder

[214] Fix | Delete

* @return the number of objects which have already been written

[215] Fix | Delete

*/

[216] Fix | Delete

GIT_EXTERN(size_t) git_packbuilder_written(git_packbuilder *pb);

[217] Fix | Delete

[218] Fix | Delete

/** Packbuilder progress notification function */

[219] Fix | Delete

typedef int GIT_CALLBACK(git_packbuilder_progress)(

[220] Fix | Delete

int stage,

[221] Fix | Delete

uint32_t current,

[222] Fix | Delete

uint32_t total,

[223] Fix | Delete

void *payload);

[224] Fix | Delete

[225] Fix | Delete

/**

[226] Fix | Delete

* Set the callbacks for a packbuilder

[227] Fix | Delete

*

[228] Fix | Delete

* @param pb The packbuilder object

[229] Fix | Delete

* @param progress_cb Function to call with progress information during

[230] Fix | Delete

* pack building. Be aware that this is called inline with pack building

[231] Fix | Delete

* operations, so performance may be affected.

[232] Fix | Delete

* @param progress_cb_payload Payload for progress callback.

[233] Fix | Delete

* @return 0 or an error code

[234] Fix | Delete

*/

[235] Fix | Delete

GIT_EXTERN(int) git_packbuilder_set_callbacks(

[236] Fix | Delete

git_packbuilder *pb,

[237] Fix | Delete

git_packbuilder_progress progress_cb,

[238] Fix | Delete

void *progress_cb_payload);

[239] Fix | Delete

[240] Fix | Delete

/**

[241] Fix | Delete

* Free the packbuilder and all associated data

[242] Fix | Delete

*

[243] Fix | Delete

* @param pb The packbuilder

[244] Fix | Delete

*/

[245] Fix | Delete

GIT_EXTERN(void) git_packbuilder_free(git_packbuilder *pb);

[246] Fix | Delete

[247] Fix | Delete

/** @} */

[248] Fix | Delete

GIT_END_DECL

[249] Fix | Delete

#endif

[250] Fix | Delete

[251] Fix | Delete