include/git2/odb.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_odb_h__
   8 #define INCLUDE_git_odb_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13
  14 /**
  15  * @file git2/odb.h
  16  * @brief Git object database routines
  17  * @defgroup git_odb Git object database routines
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 /**
  24  * Function type for callbacks from git_odb_foreach.
  25  */
  26 typedef int (*git_odb_foreach_cb)(const git_oid *id, void *payload);
  27
  28 /**
  29  * Create a new object database with no backends.
  30  *
  31  * Before the ODB can be used for read/writing, a custom database
  32  * backend must be manually added using `git_odb_add_backend()`
  33  *
  34  * @param out location to store the database pointer, if opened.
  35  *                      Set to NULL if the open failed.
  36  * @return 0 or an error code
  37  */
  38 GIT_EXTERN(int) git_odb_new(git_odb **out);
  39
  40 /**
  41  * Create a new object database and automatically add
  42  * the two default backends:
  43  *
  44  *      - git_odb_backend_loose: read and write loose object files
  45  *              from disk, assuming `objects_dir` as the Objects folder
  46  *
  47  *      - git_odb_backend_pack: read objects from packfiles,
  48  *              assuming `objects_dir` as the Objects folder which
  49  *              contains a 'pack/' folder with the corresponding data
  50  *
  51  * @param out location to store the database pointer, if opened.
  52  *                      Set to NULL if the open failed.
  53  * @param objects_dir path of the backends' "objects" directory.
  54  * @return 0 or an error code
  55  */
  56 GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir);
  57
  58 /**
  59  * Add an on-disk alternate to an existing Object DB.
  60  *
  61  * Note that the added path must point to an `objects`, not
  62  * to a full repository, to use it as an alternate store.
  63  *
  64  * Alternate backends are always checked for objects *after*
  65  * all the main backends have been exhausted.
  66  *
  67  * Writing is disabled on alternate backends.
  68  *
  69  * @param odb database to add the backend to
  70  * @param path path to the objects folder for the alternate
  71  * @return 0 on success; error code otherwise
  72  */
  73 GIT_EXTERN(int) git_odb_add_disk_alternate(git_odb *odb, const char *path);
  74
  75 /**
  76  * Close an open object database.
  77  *
  78  * @param db database pointer to close. If NULL no action is taken.
  79  */
  80 GIT_EXTERN(void) git_odb_free(git_odb *db);
  81
  82 /**
  83  * Read an object from the database.
  84  *
  85  * This method queries all available ODB backends
  86  * trying to read the given OID.
  87  *
  88  * The returned object is reference counted and
  89  * internally cached, so it should be closed
  90  * by the user once it's no longer in use.
  91  *
  92  * @param out pointer where to store the read object
  93  * @param db database to search for the object in.
  94  * @param id identity of the object to read.
  95  * @return
  96  * - 0 if the object was read;
  97  * - GIT_ENOTFOUND if the object is not in the database.
  98  */
  99 GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id);
 100
 101 /**
 102  * Read an object from the database, given a prefix
 103  * of its identifier.
 104  *
 105  * This method queries all available ODB backends
 106  * trying to match the 'len' first hexadecimal
 107  * characters of the 'short_id'.
 108  * The remaining (GIT_OID_HEXSZ-len)*4 bits of
 109  * 'short_id' must be 0s.
 110  * 'len' must be at least GIT_OID_MINPREFIXLEN,
 111  * and the prefix must be long enough to identify
 112  * a unique object in all the backends; the
 113  * method will fail otherwise.
 114  *
 115  * The returned object is reference counted and
 116  * internally cached, so it should be closed
 117  * by the user once it's no longer in use.
 118  *
 119  * @param out pointer where to store the read object
 120  * @param db database to search for the object in.
 121  * @param short_id a prefix of the id of the object to read.
 122  * @param len the length of the prefix
 123  * @return
 124  * - 0 if the object was read;
 125  * - GIT_ENOTFOUND if the object is not in the database.
 126  * - GIT_EAMBIGUOUS if the prefix is ambiguous (several objects match the prefix)
 127  */
 128 GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git_oid *short_id, size_t len);
 129
 130 /**
 131  * Read the header of an object from the database, without
 132  * reading its full contents.
 133  *
 134  * The header includes the length and the type of an object.
 135  *
 136  * Note that most backends do not support reading only the header
 137  * of an object, so the whole object will be read and then the
 138  * header will be returned.
 139  *
 140  * @param len_out pointer where to store the length
 141  * @param type_out pointer where to store the type
 142  * @param db database to search for the object in.
 143  * @param id identity of the object to read.
 144  * @return
 145  * - 0 if the object was read;
 146  * - GIT_ENOTFOUND if the object is not in the database.
 147  */
 148 GIT_EXTERN(int) git_odb_read_header(size_t *len_out, git_otype *type_out, git_odb *db, const git_oid *id);
 149
 150 /**
 151  * Determine if the given object can be found in the object database.
 152  *
 153  * @param db database to be searched for the given object.
 154  * @param id the object to search for.
 155  * @return
 156  * - 1, if the object was found
 157  * - 0, otherwise
 158  */
 159 GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id);
 160
 161 /**
 162  * Refresh the object database to load newly added files.
 163  *
 164  * If the object databases have changed on disk while the library
 165  * is running, this function will force a reload of the underlying
 166  * indexes.
 167  *
 168  * Use this function when you're confident that an external
 169  * application has tampered with the ODB.
 170  *
 171  * NOTE that it is not necessary to call this function at all. The
 172  * library will automatically attempt to refresh the ODB
 173  * when a lookup fails, to see if the looked up object exists
 174  * on disk but hasn't been loaded yet.
 175  *
 176  * @param db database to refresh
 177  * @return 0 on success, error code otherwise
 178  */
 179 GIT_EXTERN(int) git_odb_refresh(struct git_odb *db);
 180
 181 /**
 182  * List all objects available in the database
 183  *
 184  * The callback will be called for each object available in the
 185  * database. Note that the objects are likely to be returned in the index
 186  * order, which would make accessing the objects in that order inefficient.
 187  * Return a non-zero value from the callback to stop looping.
 188  *
 189  * @param db database to use
 190  * @param cb the callback to call for each object
 191  * @param payload data to pass to the callback
 192  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
 193  */
 194 GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload);
 195
 196 /**
 197  * Write an object directly into the ODB
 198  *
 199  * This method writes a full object straight into the ODB.
 200  * For most cases, it is preferred to write objects through a write
 201  * stream, which is both faster and less memory intensive, specially
 202  * for big objects.
 203  *
 204  * This method is provided for compatibility with custom backends
 205  * which are not able to support streaming writes
 206  *
 207  * @param out pointer to store the OID result of the write
 208  * @param odb object database where to store the object
 209  * @param data buffer with the data to store
 210  * @param len size of the buffer
 211  * @param type type of the data to store
 212  * @return 0 or an error code
 213  */
 214 GIT_EXTERN(int) git_odb_write(git_oid *out, git_odb *odb, const void *data, size_t len, git_otype type);
 215
 216 /**
 217  * Open a stream to write an object into the ODB
 218  *
 219  * The type and final length of the object must be specified
 220  * when opening the stream.
 221  *
 222  * The returned stream will be of type `GIT_STREAM_WRONLY` and
 223  * will have the following methods:
 224  *
 225  *              - stream->write: write `n` bytes into the stream
 226  *              - stream->finalize_write: close the stream and store the object in
 227  *                      the odb
 228  *              - stream->free: free the stream
 229  *
 230  * The streaming write won't be effective until `stream->finalize_write`
 231  * is called and returns without an error
 232  *
 233  * The stream must always be free'd or will leak memory.
 234  *
 235  * @see git_odb_stream
 236  *
 237  * @param out pointer where to store the stream
 238  * @param db object database where the stream will write
 239  * @param size final size of the object that will be written
 240  * @param type type of the object that will be written
 241  * @return 0 if the stream was created; error code otherwise
 242  */
 243 GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **out, git_odb *db, size_t size, git_otype type);
 244
 245 /**
 246  * Open a stream to read an object from the ODB
 247  *
 248  * Note that most backends do *not* support streaming reads
 249  * because they store their objects as compressed/delta'ed blobs.
 250  *
 251  * It's recommended to use `git_odb_read` instead, which is
 252  * assured to work on all backends.
 253  *
 254  * The returned stream will be of type `GIT_STREAM_RDONLY` and
 255  * will have the following methods:
 256  *
 257  *              - stream->read: read `n` bytes from the stream
 258  *              - stream->free: free the stream
 259  *
 260  * The stream must always be free'd or will leak memory.
 261  *
 262  * @see git_odb_stream
 263  *
 264  * @param out pointer where to store the stream
 265  * @param db object database where the stream will read from
 266  * @param oid oid of the object the stream will read from
 267  * @return 0 if the stream was created; error code otherwise
 268  */
 269 GIT_EXTERN(int) git_odb_open_rstream(git_odb_stream **out, git_odb *db, const git_oid *oid);
 270
 271 /**
 272  * Open a stream for writing a pack file to the ODB.
 273  *
 274  * If the ODB layer understands pack files, then the given
 275  * packfile will likely be streamed directly to disk (and a
 276  * corresponding index created).  If the ODB layer does not
 277  * understand pack files, the objects will be stored in whatever
 278  * format the ODB layer uses.
 279  *
 280  * @see git_odb_writepack
 281  *
 282  * @param out pointer to the writepack functions
 283  * @param db object database where the stream will read from
 284  * @param progress_cb function to call with progress information.
 285  * Be aware that this is called inline with network and indexing operations,
 286  * so performance may be affected.
 287  * @param progress_payload payload for the progress callback
 288  */
 289 GIT_EXTERN(int) git_odb_write_pack(
 290         git_odb_writepack **out,
 291         git_odb *db,
 292         git_transfer_progress_callback progress_cb,
 293         void *progress_payload);
 294
 295 /**
 296  * Determine the object-ID (sha1 hash) of a data buffer
 297  *
 298  * The resulting SHA-1 OID will be the identifier for the data
 299  * buffer as if the data buffer it were to written to the ODB.
 300  *
 301  * @param out the resulting object-ID.
 302  * @param data data to hash
 303  * @param len size of the data
 304  * @param type of the data to hash
 305  * @return 0 or an error code
 306  */
 307 GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_otype type);
 308
 309 /**
 310  * Read a file from disk and fill a git_oid with the object id
 311  * that the file would have if it were written to the Object
 312  * Database as an object of the given type (w/o applying filters).
 313  * Similar functionality to git.git's `git hash-object` without
 314  * the `-w` flag, however, with the --no-filters flag.
 315  * If you need filters, see git_repository_hashfile.
 316  *
 317  * @param out oid structure the result is written into.
 318  * @param path file to read and determine object id for
 319  * @param type the type of the object that will be hashed
 320  * @return 0 or an error code
 321  */
 322 GIT_EXTERN(int) git_odb_hashfile(git_oid *out, const char *path, git_otype type);
 323
 324 /**
 325  * Close an ODB object
 326  *
 327  * This method must always be called once a `git_odb_object` is no
 328  * longer needed, otherwise memory will leak.
 329  *
 330  * @param object object to close
 331  */
 332 GIT_EXTERN(void) git_odb_object_free(git_odb_object *object);
 333
 334 /**
 335  * Return the OID of an ODB object
 336  *
 337  * This is the OID from which the object was read from
 338  *
 339  * @param object the object
 340  * @return a pointer to the OID
 341  */
 342 GIT_EXTERN(const git_oid *) git_odb_object_id(git_odb_object *object);
 343
 344 /**
 345  * Return the data of an ODB object
 346  *
 347  * This is the uncompressed, raw data as read from the ODB,
 348  * without the leading header.
 349  *
 350  * This pointer is owned by the object and shall not be free'd.
 351  *
 352  * @param object the object
 353  * @return a pointer to the data
 354  */
 355 GIT_EXTERN(const void *) git_odb_object_data(git_odb_object *object);
 356
 357 /**
 358  * Return the size of an ODB object
 359  *
 360  * This is the real size of the `data` buffer, not the
 361  * actual size of the object.
 362  *
 363  * @param object the object
 364  * @return the size
 365  */
 366 GIT_EXTERN(size_t) git_odb_object_size(git_odb_object *object);
 367
 368 /**
 369  * Return the type of an ODB object
 370  *
 371  * @param object the object
 372  * @return the type
 373  */
 374 GIT_EXTERN(git_otype) git_odb_object_type(git_odb_object *object);
 375
 376 /**
 377  * Add a custom backend to an existing Object DB
 378  *
 379  * The backends are checked in relative ordering, based on the
 380  * value of the `priority` parameter.
 381  *
 382  * Read <odb_backends.h> for more information.
 383  *
 384  * @param odb database to add the backend to
 385  * @param backend pointer to a git_odb_backend instance
 386  * @param priority Value for ordering the backends queue
 387  * @return 0 on success; error code otherwise
 388  */
 389 GIT_EXTERN(int) git_odb_add_backend(git_odb *odb, git_odb_backend *backend, int priority);
 390
 391 /**
 392  * Add a custom backend to an existing Object DB; this
 393  * backend will work as an alternate.
 394  *
 395  * Alternate backends are always checked for objects *after*
 396  * all the main backends have been exhausted.
 397  *
 398  * The backends are checked in relative ordering, based on the
 399  * value of the `priority` parameter.
 400  *
 401  * Writing is disabled on alternate backends.
 402  *
 403  * Read <odb_backends.h> for more information.
 404  *
 405  * @param odb database to add the backend to
 406  * @param backend pointer to a git_odb_backend instance
 407  * @param priority Value for ordering the backends queue
 408  * @return 0 on success; error code otherwise
 409  */
 410 GIT_EXTERN(int) git_odb_add_alternate(git_odb *odb, git_odb_backend *backend, int priority);
 411
 412 /**
 413  * Get the number of ODB backend objects
 414  *
 415  * @param odb object database
 416  * @return number of backends in the ODB
 417  */
 418 GIT_EXTERN(size_t) git_odb_num_backends(git_odb *odb);
 419
 420 /**
 421  * Lookup an ODB backend object by index
 422  *
 423  * @param out output pointer to ODB backend at pos
 424  * @param odb object database
 425  * @param pos index into object database backend list
 426  * @return 0 on success; GIT_ENOTFOUND if pos is invalid; other errors < 0
 427  */
 428 GIT_EXTERN(int) git_odb_get_backend(git_odb_backend **out, git_odb *odb, size_t pos);
 429
 430 /** @} */
 431 GIT_END_DECL
 432 #endif