include/git2/indexer.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef _INCLUDE_git_indexer_h__
0008 #define _INCLUDE_git_indexer_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "oid.h"
0013
0014 GIT_BEGIN_DECL
0015
0016 /** A git indexer object */
0017 typedef struct git_indexer git_indexer;
0018
0019 /**
0020  * This structure is used to provide callers information about the
0021  * progress of indexing a packfile, either directly or part of a
0022  * fetch or clone that downloads a packfile.
0023  */
0024 typedef struct git_indexer_progress {
0025     /** number of objects in the packfile being indexed */
0026     unsigned int total_objects;
0027
0028     /** received objects that have been hashed */
0029     unsigned int indexed_objects;
0030
0031     /** received_objects: objects which have been downloaded */
0032     unsigned int received_objects;
0033
0034     /**
0035      * locally-available objects that have been injected in order
0036      * to fix a thin pack
0037      */
0038     unsigned int local_objects;
0039
0040     /** number of deltas in the packfile being indexed */
0041     unsigned int total_deltas;
0042
0043     /** received deltas that have been indexed */
0044     unsigned int indexed_deltas;
0045
0046     /** size of the packfile received up to now */
0047     size_t received_bytes;
0048 } git_indexer_progress;
0049
0050 /**
0051  * Type for progress callbacks during indexing.  Return a value less
0052  * than zero to cancel the indexing or download.
0053  *
0054  * @param stats Structure containing information about the state of the transfer
0055  * @param payload Payload provided by caller
0056  */
0057 typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload);
0058
0059 /**
0060  * Options for indexer configuration
0061  */
0062 typedef struct git_indexer_options {
0063     unsigned int version;
0064
0065 #ifdef GIT_EXPERIMENTAL_SHA256
0066     /** permissions to use creating packfile or 0 for defaults */
0067     unsigned int mode;
0068
0069     /**
0070      * object database from which to read base objects when
0071      * fixing thin packs. This can be NULL if there are no thin
0072      * packs; if a thin pack is encountered, an error will be
0073      * returned if there are bases missing.
0074      */
0075     git_odb *odb;
0076 #endif
0077
0078     /** progress_cb function to call with progress information */
0079     git_indexer_progress_cb progress_cb;
0080
0081     /** progress_cb_payload payload for the progress callback */
0082     void *progress_cb_payload;
0083
0084     /** Do connectivity checks for the received pack */
0085     unsigned char verify;
0086 } git_indexer_options;
0087
0088 #define GIT_INDEXER_OPTIONS_VERSION 1
0089 #define GIT_INDEXER_OPTIONS_INIT { GIT_INDEXER_OPTIONS_VERSION }
0090
0091 /**
0092  * Initializes a `git_indexer_options` with default values. Equivalent to
0093  * creating an instance with GIT_INDEXER_OPTIONS_INIT.
0094  *
0095  * @param opts the `git_indexer_options` struct to initialize.
0096  * @param version Version of struct; pass `GIT_INDEXER_OPTIONS_VERSION`
0097  * @return Zero on success; -1 on failure.
0098  */
0099 GIT_EXTERN(int) git_indexer_options_init(
0100     git_indexer_options *opts,
0101     unsigned int version);
0102
0103 #ifdef GIT_EXPERIMENTAL_SHA256
0104 /**
0105  * Create a new indexer instance
0106  *
0107  * @param out where to store the indexer instance
0108  * @param path to the directory where the packfile should be stored
0109  * @param oid_type the oid type to use for objects
0110  * @return 0 or an error code.
0111  */
0112 GIT_EXTERN(int) git_indexer_new(
0113         git_indexer **out,
0114         const char *path,
0115         git_oid_t oid_type,
0116         git_indexer_options *opts);
0117 #else
0118 /**
0119  * Create a new indexer instance
0120  *
0121  * @param out where to store the indexer instance
0122  * @param path to the directory where the packfile should be stored
0123  * @param mode permissions to use creating packfile or 0 for defaults
0124  * @param odb object database from which to read base objects when
0125  * fixing thin packs. Pass NULL if no thin pack is expected (an error
0126  * will be returned if there are bases missing)
0127  * @param opts Optional structure containing additional options. See
0128  * `git_indexer_options` above.
0129  * @return 0 or an error code.
0130  */
0131 GIT_EXTERN(int) git_indexer_new(
0132         git_indexer **out,
0133         const char *path,
0134         unsigned int mode,
0135         git_odb *odb,
0136         git_indexer_options *opts);
0137 #endif
0138
0139 /**
0140  * Add data to the indexer
0141  *
0142  * @param idx the indexer
0143  * @param data the data to add
0144  * @param size the size of the data in bytes
0145  * @param stats stat storage
0146  * @return 0 or an error code.
0147  */
0148 GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t size, git_indexer_progress *stats);
0149
0150 /**
0151  * Finalize the pack and index
0152  *
0153  * Resolve any pending deltas and write out the index file
0154  *
0155  * @param idx the indexer
0156  * @param stats Stat storage.
0157  * @return 0 or an error code.
0158  */
0159 GIT_EXTERN(int) git_indexer_commit(git_indexer *idx, git_indexer_progress *stats);
0160
0161 #ifndef GIT_DEPRECATE_HARD
0162 /**
0163  * Get the packfile's hash
0164  *
0165  * A packfile's name is derived from the sorted hashing of all object
0166  * names. This is only correct after the index has been finalized.
0167  *
0168  * @deprecated use git_indexer_name
0169  * @param idx the indexer instance
0170  * @return the packfile's hash
0171  */
0172 GIT_EXTERN(const git_oid *) git_indexer_hash(const git_indexer *idx);
0173 #endif
0174
0175 /**
0176  * Get the unique name for the resulting packfile.
0177  *
0178  * The packfile's name is derived from the packfile's content.
0179  * This is only correct after the index has been finalized.
0180  *
0181  * @param idx the indexer instance
0182  * @return a NUL terminated string for the packfile name
0183  */
0184 GIT_EXTERN(const char *) git_indexer_name(const git_indexer *idx);
0185
0186 /**
0187  * Free the indexer and its resources
0188  *
0189  * @param idx the indexer to free
0190  */
0191 GIT_EXTERN(void) git_indexer_free(git_indexer *idx);
0192
0193 GIT_END_DECL
0194
0195 #endif