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  * @return 0 or an error code.
 102  */
 103 GIT_EXTERN(int) git_indexer_new(
 104                 git_indexer **out,
 105                 const char *path,
 106                 unsigned int mode,
 107                 git_odb *odb,
 108                 git_indexer_options *opts);
 109
 110 /**
 111  * Add data to the indexer
 112  *
 113  * @param idx the indexer
 114  * @param data the data to add
 115  * @param size the size of the data in bytes
 116  * @param stats stat storage
 117  * @return 0 or an error code.
 118  */
 119 GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t size, git_indexer_progress *stats);
 120
 121 /**
 122  * Finalize the pack and index
 123  *
 124  * Resolve any pending deltas and write out the index file
 125  *
 126  * @param idx the indexer
 127  * @param stats Stat storage.
 128  * @return 0 or an error code.
 129  */
 130 GIT_EXTERN(int) git_indexer_commit(git_indexer *idx, git_indexer_progress *stats);
 131
 132 #ifndef GIT_DEPRECATE_HARD
 133 /**
 134  * Get the packfile's hash
 135  *
 136  * A packfile's name is derived from the sorted hashing of all object
 137  * names. This is only correct after the index has been finalized.
 138  *
 139  * @deprecated use git_indexer_name
 140  * @param idx the indexer instance
 141  * @return the packfile's hash
 142  */
 143 GIT_EXTERN(const git_oid *) git_indexer_hash(const git_indexer *idx);
 144 #endif
 145
 146 /**
 147  * Get the unique name for the resulting packfile.
 148  *
 149  * The packfile's name is derived from the packfile's content.
 150  * This is only correct after the index has been finalized.
 151  *
 152  * @param idx the indexer instance
 153  * @return a NUL terminated string for the packfile name
 154  */
 155 GIT_EXTERN(const char *) git_indexer_name(const git_indexer *idx);
 156
 157 /**
 158  * Free the indexer and its resources
 159  *
 160  * @param idx the indexer to free
 161  */
 162 GIT_EXTERN(void) git_indexer_free(git_indexer *idx);
 163
 164 GIT_END_DECL
 165
 166 #endif