include/git2/indexer.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   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_indexer_h__
   8 #define _INCLUDE_git_indexer_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13
  14 GIT_BEGIN_DECL
  15
  16 /** A git indexer object */
  17 typedef struct git_indexer git_indexer;
  18
  19 /**
  20  * This structure is used to provide callers information about the
  21  * progress of indexing a packfile, either directly or part of a
  22  * fetch or clone that downloads a packfile.
  23  */
  24 typedef struct git_indexer_progress {
  25         /** number of objects in the packfile being indexed */
  26         unsigned int total_objects;
  27
  28         /** received objects that have been hashed */
  29         unsigned int indexed_objects;
  30
  31         /** received_objects: objects which have been downloaded */
  32         unsigned int received_objects;
  33
  34         /**
  35          * locally-available objects that have been injected in order
  36          * to fix a thin pack
  37          */
  38         unsigned int local_objects;
  39
  40         /** number of deltas in the packfile being indexed */
  41         unsigned int total_deltas;
  42
  43         /** received deltas that have been indexed */
  44         unsigned int indexed_deltas;
  45
  46         /** size of the packfile received up to now */
  47         size_t received_bytes;
  48 } git_indexer_progress;
  49
  50 /**
  51  * Type for progress callbacks during indexing.  Return a value less
  52  * than zero to cancel the indexing or download.
  53  *
  54  * @param stats Structure containing information about the state of the transfer
  55  * @param payload Payload provided by caller
  56  */
  57 typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload);
  58
  59 /**
  60  * Options for indexer configuration
  61  */
  62 typedef struct git_indexer_options {
  63         unsigned int version;
  64
  65         /** progress_cb function to call with progress information */
  66         git_indexer_progress_cb progress_cb;
  67
  68         /** progress_cb_payload payload for the progress callback */
  69         void *progress_cb_payload;
  70
  71         /** Do connectivity checks for the received pack */
  72         unsigned char verify;
  73 } git_indexer_options;
  74
  75 #define GIT_INDEXER_OPTIONS_VERSION 1
  76 #define GIT_INDEXER_OPTIONS_INIT { GIT_INDEXER_OPTIONS_VERSION }
  77
  78 /**
  79  * Initializes a `git_indexer_options` with default values. Equivalent to
  80  * creating an instance with GIT_INDEXER_OPTIONS_INIT.
  81  *
  82  * @param opts the `git_indexer_options` struct to initialize.
  83  * @param version Version of struct; pass `GIT_INDEXER_OPTIONS_VERSION`
  84  * @return Zero on success; -1 on failure.
  85  */
  86 GIT_EXTERN(int) git_indexer_options_init(
  87         git_indexer_options *opts,
  88         unsigned int version);
  89
  90 /**
  91  * Create a new indexer instance
  92  *
  93  * @param out where to store the indexer instance
  94  * @param path to the directory where the packfile should be stored
  95  * @param mode permissions to use creating packfile or 0 for defaults
  96  * @param odb object database from which to read base objects when
  97  * fixing thin packs. Pass NULL if no thin pack is expected (an error
  98  * will be returned if there are bases missing)
  99  * @param opts Optional structure containing additional options. See
 100  * `git_indexer_options` above.
 101  */
 102 GIT_EXTERN(int) git_indexer_new(
 103                 git_indexer **out,
 104                 const char *path,
 105                 unsigned int mode,
 106                 git_odb *odb,
 107                 git_indexer_options *opts);
 108
 109 /**
 110  * Add data to the indexer
 111  *
 112  * @param idx the indexer
 113  * @param data the data to add
 114  * @param size the size of the data in bytes
 115  * @param stats stat storage
 116  */
 117 GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t size, git_indexer_progress *stats);
 118
 119 /**
 120  * Finalize the pack and index
 121  *
 122  * Resolve any pending deltas and write out the index file
 123  *
 124  * @param idx the indexer
 125  */
 126 GIT_EXTERN(int) git_indexer_commit(git_indexer *idx, git_indexer_progress *stats);
 127
 128 /**
 129  * Get the packfile's hash
 130  *
 131  * A packfile's name is derived from the sorted hashing of all object
 132  * names. This is only correct after the index has been finalized.
 133  *
 134  * @param idx the indexer instance
 135  */
 136 GIT_EXTERN(const git_oid *) git_indexer_hash(const git_indexer *idx);
 137
 138 /**
 139  * Free the indexer and its resources
 140  *
 141  * @param idx the indexer to free
 142  */
 143 GIT_EXTERN(void) git_indexer_free(git_indexer *idx);
 144
 145 GIT_END_DECL
 146
 147 #endif